Build and register APIs with the Azure API Center extension for Visual Studio Code

  • Article

API developers in your organization can build and register APIs in your API center inventory by using the Azure API Center extension for Visual Studio Code. API developers can:

  • Add an existing API to an API center as a one-time operation, or integrate a development pipeline to register APIs as part of a CI/CD workflow.
  • Use GitHub Copilot to generate new OpenAPI specs from API code.
  • Use natural language prompts with the API Center plugin for GitHub Copilot for Azure to create new OpenAPI specs.

API developers can also take advantage of features in the extension to discover and consume APIs in the API center and ensure API governance.

Prerequisites

The following Visual Studio Code extensions are needed for the specified scenarios:

Setup

  1. Install the Azure API Center extension for Visual Studio Code from the Visual Studio Code Marketplace. Install other extensions as needed.

    Note

    Where noted, certain features are available only in the Azure API Center extension's pre-release version. When installing the extension from the Visual Studio Code Marketplace, you can choose to install the release version or a pre-release version. Switch between the two versions at any time by using the extension's Manage button context menu in the Extensions view.

  2. In Visual Studio Code, in the Activity Bar on the left, select API Center.

    Screenshot of API Center extension in the activity bar.

  3. If you're not signed in to your Azure account, select Sign in to Azure..., and follow the prompts to sign in. Select an Azure subscription with the API center (or API centers) you wish to view APIs from. You can also filter on specific subscriptions if you have many to view from.

Register an API - step by step

The following steps register an API in your API center as a one-time operation.

  1. Use the Ctrl+Shift+P keyboard shortcut to open the Command Palette. Type Azure API Center: Register API and hit Enter.
  2. Select Manual.
  3. Select the API center to register APIs with.
  4. Answer prompts with information including API title, type, version title, version lifecycle, definition title, specification name, and definition file to complete API registration.

The API is added to your API center inventory.

Register APIs - CI/CD pipeline

The following steps register an API in your API center with a CI/CD pipeline. With this option, add a preconfigured GitHub or Azure DevOps pipeline to your active Visual Studio Code workspace that is run as part of a CI/CD workflow on each commit to source control. It's recommended to inventory APIs with your API center using CI/CD to ensure API metadata including specification and version stay current in your API center as the API continues to evolve over time.

  1. Use the Ctrl+Shift+P keyboard shortcut to open the Command Palette. Type Azure API Center: Register API and hit Enter.
  2. Select CI/CD.
  3. Select either GitHub or Azure DevOps, depending on your preferred source control mechanism. A Visual Studio Code workspace must be open for the Azure API Center extension to add a pipeline to your workspace. After the file is added, complete steps documented in the CI/CD pipeline file itself to configure required environment variables and identity. On push to source control, the API is registered in your API center.

Learn more about setting up a GitHub Actions workflow to register APIs with your API center.

Generate OpenAPI spec from API code

Use the power of GitHub Copilot with the Azure API Center extension for Visual Studio Code to create an OpenAPI specification file from your API code. Right-click on the API code, select Copilot from the options, and select Generate API documentation. GitHub Copilot creates an OpenAPI specification file.

Note

This feature is available in the pre-release version of the API Center extension.

Animation showing how to use GitHub Copilot to generate an OpenAPI spec from code.

After generating the OpenAPI specification file and checking for accuracy, you can register the API with your API center using the Azure API Center: Register API command.

Generate OpenAPI spec using natural language prompts

The API Center plugin for GitHub Copilot for Azure (preview) helps you design new APIs starting from natural language prompts. With AI assistance, quickly generate an OpenAPI spec for API development that complies with your organization's standards.

Note

This feature is available in the pre-release version of the API Center extension.

  1. If desired, set an active API style guide. Use the Ctrl+Shift+P keyboard shortcut to open the Command Palette. Type Azure API Center: Set API Style Guide, make a selection, and hit Enter.

    If no style guide is set, the default spectral:oas ruleset is used.

  2. In the chat panel, make a request in natural language to the @azure agent to describe what the API does. Example:

    @azure Generate OpenAPI spec: An API that allows customers to pay for an order using various payment methods such as cash, checks, credit cards, and debit cards.

    The agent responds with an OpenAPI specification document.

    Screenshot showing how to use @azure extension to generate an OpenAPI spec from a prompt.

  3. Review the generated output for accuracy and compliance with your API style guide. Refine the prompt if needed to regenerate.

    Tip

    Effective prompts focus on an API's business requirements rather than implementation details. Shorter prompts sometimes work better than longer ones.

  4. When it meets your requirements, save the generated OpenAPI specification to a file.

  5. Register the API with your API center. Select Register your API in API Center button in the chat panel, or select Azure API Center: Register API from the Command Palette, and follow the prompts.

Related content