Skip to content

Dataplane Codegen Quick Start For Swagger

Jump to bottom
Yuchao Yan edited this page Feb 28, 2024 · 9 revisions

Getting Started - Generate SDK With Dataplane Codegen

Support

For more questions and general overview of the process, please refer to https://aka.ms/azsdk/dpcodegen

Foreword

We advise use Dataplane-Codegen-Quick-Start-with-tools to generate SDK code which is very convenient. Of course, if you want to know more details about how to generate SDK code with DPG, please go ahead for next part.

Prerequisites

Setup your repo

Project service name and package name

Two key pieces of information for your project are the service_name and package_name.

The service_name is the short name for the Azure service. The service_name should match across all the SDK language repos and should be name of the directory in the specification folder of the azure-rest-api-specs repo that contains the REST API definition file. An example is Service Bus, whose API definitions are in the specifications/servicebus folder of the azure-rest-api-specs repo, and uses the service_name "servicebus". Not every service follows this convention, but it should be the standard unless there are strong reasons to deviate.

In Python, a project's package name is the name used to publish the package in PyPI. For data plane libraries (management plane uses a different convention), the package_name could be just azure-{service_name}. An example is "azure-servicebus".

Some services may need several different packages. For these cases a third component, the module_name, is added to the package_name, as azure-{service_name}-{module_name}. The module_name usually comes from the name of the REST API file itself or one of the directories toward the end of the file path. An example is the Synapse service, with packages azure-synapse, azure-synapse-accesscontrol, azure-synapse-artifacts, etc.

Project folder structure

Before we start, we probably should get to know the project folder for SDK repo.

Normally, the folder structure would be something like:

  • sdk/{service_name}/{package_name}: the PROJECT_ROOT folder
    • azure/{service_name}/{module_name} : folder where generated code is.
    • /swagger: folder of configuration file which is used to generate SDK code with autorest
    • /tests: folder of test files
    • /samples: folder of sample files
    • azure-{service_name}-{module_name}: package name. Usually, package name is same with part of ${PROJECT_ROOT} folder. After release, you can find it in pypi. For example: you can find azure-messaging-webpubsubservice in pypi.
    • there are also some other files (like setup.py, README.md, etc) which are necessary for a complete package.

More details on the structure of Azure SDK repos is available in the Azure SDK common repo.

How to generate SDK code with Dataplane Codegen

We are working on to automatically generate everything right now, but currently we still need some manual work to get a releasable package. Here're the steps of how to get the package.

  1. Create the ${PROJECT_ROOT} folder if it does not already exist

  2. Create a README.md file under ${PROJECT_ROOT}/swagger

    This README.md file will hold the options to be passed to autorest to generate the code. Storing these options in a file in the SDK repo helps make SDK generation reproducible.

    Here's an example of the README.md

    # Azure Purview for Python

> see https://aka.ms/autorest

### Settings

```yaml
input-file: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/webpubsub/data-plane/WebPubSub/stable/2021-10-01/webpubsub.json
output-folder: ../
namespace: azure.messaging.webpubsubservice
package-name: azure-messaging-webpubsubservice
license-header: MICROSOFT_MIT_NO_VERSION
title: WebPubSubServiceClient
package-version: 1.0.0b1
security: AADToken
security-scopes: https://webpubsub.azure.com/.default
```

    There are some configuration in the template and you could reference autorest/flags to get more info. We need to replace the value of package-name, title, package-version, security-scopes, into your own service's package-name, titleetc. Notes:

    • security and security-scopes: if authentication is api key, the securityand security-scopes shall be replaced with:

      security: AzureKey
security-header-name: real-service-header-name

      For more details, see authentication

  3. Run autorest to generate the SDK

    Now you can run this command using tox to generate your SDK:

tox run -e generate

If you want to go run autorest post processing on your SDK, you'll need to add the following configuration to your pyproject.toml:

[tool.generate]
autorest-post-process = true

Note: To learn more about tox, read our contributing guidelines.

  1. Add necessary files under ${PROJECT_ROOT}

    For a complete package, there are some other files you need to add:

    • CHANGELOG.md: introduce the release history and important change for each release.
    • LICENSE: license file
    • README.md: import files which introduce what the service is and how to use this package
    • dev_requirements.txt: claims some package which is needed to run test
    • MANIFEST.in: configuration file to decide which file will be included in package.
    • setup.py: most important files about dependency and supported version for Python.
    • __init__.py: it is used when package the SDK code. Please manually copy init.py under ${PROJECT_ROOT}/azure and ${PROJECT_ROOT}/azure/{service_name}

    Here is template files, and you at least need to edit item (like {{pakcage_name}}, {{package_pprint_name}}, etc) in CHANGELOG.md, README.md, setup.py, MANIFEST.in according to specific info of your own service. It is easier to understand how to edit the files with reference existing service: webpubsub.

Notes:

  • package_pprint_name: The short description for the package.

What to do after generating the SDK code

The generated code is not enough to release at once and you need to update it for better usage experience. Please follow What to do after generating the SDK code with codegen to check the code.

Clone this wiki locally