Skip to content

Commit 4dad237

Browse files
author
gitName
committed
[APIC] Refactor VSCode extension guidance
1 parent 22484aa commit 4dad237

19 files changed

+448
-140
lines changed

‎articles/api-center/build-register-apis-vscode-extension.md

Lines changed: 24 additions & 140 deletions
Large diffs are not rendered by default.

‎articles/api-center/discover-apis-vscode-extension.md

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
---
2+
title: Discover APIs - Azure API Center - VS Code extension
3+
description: API developers can use the Azure API Center extension for Visual Studio Code to discover APIs in their organization's API center.
4+
author: dlepow
5+
ms.service: azure-api-center
6+
ms.topic: how-to
7+
ms.date: 10/02/2024
8+
ms.author: danlep
9+
ms.custom:
10+
# Customer intent: As an API developer, I want to use my Visual Studio Code environment to discover and consume APIs in my organizations API center.
11+
---
12+
13+
# Discover and consume APIs with the Azure API Center extension for Visual Studio Code
14+
15+
API developers in your organization can discover and consume APIs in your [API center](overview.md) by using the Azure API Center extension for Visual Studio Code. The extension provides the following features:
16+
17+
* **Discover APIs** - Browse the APIs in your API center, and view their details and documentation.
18+
19+
* **Consume APIs** - Generate API SDK clients in their favorite language including JavaScript, TypeScript, .NET, Python, and Java, using the Microsoft Kiota engine that generates SDKs for Microsoft Graph, GitHub, and more.
20+
21+
22+
23+
> [!TIP]
24+
> Optionally enable a [platform API catalog](enable-platform-api-catalog-vscode-extension.md) for your API center in Visual Studio Code so that app developers in your organization can discover APIs in a centralized location. The platform API catalog is a read-only view of the API inventory.
25+
26+
## Prerequisites
27+
28+
[!INCLUDE [vscode-extension-basic-prerequisites](includes/vscode-extension-basic-prerequisites.md)]
29+
30+
The following Visual Studio Code extensions are optional and needed only for certain scenarios as indicated:
31+
32+
* [REST client extension](https://marketplace.visualstudio.com/items?itemName=humao.rest-client) - to send HTTP requests and view the responses in Visual Studio Code directly
33+
* [Microsoft Kiota extension](https://marketplace.visualstudio.com/items?itemName=ms-graph.kiota) - to generate API clients
34+
35+
[!INCLUDE [vscode-extension-setup](includes/vscode-extension-setup.md)]
36+
37+
## Discover APIs
38+
39+
API center resources appear in the tree view on the left-hand side. Expand an API center resource to see APIs, versions, definitions, environments, and deployments.
40+
41+
:::image type="content" source="media/discover-apis-vscode-extension/explore-api-centers.png" alt-text="Screenshot of API Center tree view in Visual Studio Code." lightbox="media/discover-apis-vscode-extension/explore-api-centers.png":::
42+
43+
Search for APIs within an API Center by using the search icon shown in the **Apis** tree view item.
44+
45+
> [!TIP]
46+
> Optionally enable a [platform API catalog](enable-platform-api-catalog-vscode-extension.md) for your API center in Visual Studio Code so that app developers in your organization can discover APIs in a centralized location. The platform API catalog is a read-only view of the API inventory.
47+
48+
## View API documentation
49+
50+
You can view the documentation for an API definition in your API center and try API operations. This feature is only available for OpenAPI-based APIs in your API center.
51+
52+
1. Expand the API Center tree view to show an API definition.
53+
1. Right-click on the definition, and select **Open API Documentation**. A new tab appears with the Swagger UI for the API definition.
54+
55+
:::image type="content" source="media/discover-apis-vscode-extension/view-api-documentation.png" alt-text="Screenshot of API documentation in Visual Studio Code." lightbox="media/discover-apis-vscode-extension/view-api-documentation.png":::
56+
57+
1. To try the API, select an endpoint, select **Try it out**, enter required parameters, and select **Execute**.
58+
59+
> [!NOTE]
60+
> Depending on the API, you might need to provide authorization credentials or an API key to try the API.
61+
62+
> [!TIP]
63+
> Using the pre-release version of the extension, you can generate API documentation in Markdown, a format that's easy to maintain and share with end users. Right-click on the definition, and select **Generate Markdown**.
64+
65+
## Generate HTTP file
66+
67+
You can view a `.http` file based on the API definition in your API center. If the REST Client extension is installed, you can make requests directory from the Visual Studio Code editor. This feature is only available for OpenAPI-based APIs in your API center.
68+
69+
1. Expand the API Center tree view to show an API definition.
70+
1. Right-click on the definition, and select **Generate HTTP File**. A new tab appears that renders a .http document populated by the API specification.
71+
72+
:::image type="content" source="media/discover-apis-vscode-extension/generate-http-file.png" alt-text="Screenshot of generating a .http file in Visual Studio Code." lightbox="media/discover-apis-vscode-extension/generate-http-file.png":::
73+
74+
1. To make a request, select an endpoint, and select **Send Request**.
75+
76+
> [!NOTE]
77+
> Depending on the API, you might need to provide authorization credentials or an API key to make the request.
78+
79+
## Generate API client
80+
81+
Use the Microsoft Kiota extension to generate an API client for your favorite language. This feature is only available for OpenAPI-based APIs in your API center.
82+
83+
1. Expand the API Center tree view to show an API definition.
84+
1. Right-click on the definition, and select **Generate API Client**. The **Kiota OpenAPI Generator** pane appears.
85+
1. Select the API endpoints and HTTP operations you wish to include in your SDKs.
86+
1. Select **Generate API client**.
87+
1. Enter configuration details about the SDK name, namespace, and output directory.
88+
1. Select the language for the generated SDK.
89+
90+
:::image type="content" source="media/discover-apis-vscode-extension/generate-api-client.png" alt-text="Screenshot of Kiota OpenAPI Explorer in Visual Studio Code." lightbox="media/discover-apis-vscode-extension/generate-api-client.png":::
91+
92+
The client is generated.
93+
94+
For details on using the Kiota extension, see [Microsoft Kiota extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-graph.kiota).
95+
96+
## Export API specification
97+
98+
You can export an API specification from a definition and then download it as a file.
99+
100+
To export a specification in the extension's tree view:
101+
102+
1. Expand the API Center tree view to show an API definition.
103+
1. Right-click on the definition, and select **Export API Specification Document**. A new tab appears that renders an API specification document.
104+
105+
:::image type="content" source="media/discover-apis-vscode-extension/export-specification.png" alt-text="Screenshot of exporting API specification in Visual Studio Code." lightbox="media/discover-apis-vscode-extension/export-specification.png":::
106+
107+
You can also export a specification using the Command Palette:
108+
109+
1. Type the **Ctrl+Shift+P** keyboard shortcut to open the Command Palette.
110+
1. Select **Azure API Center: Export API Specification Document**.
111+
1. Make selections to navigate to an API definition. A new tab appears that renders an API specification document.
112+
113+
## Related content
114+
115+
* [Azure API Center - key concepts](key-concepts.md)
116+
* [Build and register APIs with the Azure API Center extension for Visual Studio Code](build-register-apis-vscode-extension.md)
117+
* [Govern APIs with the Azure API Center extension for Visual Studio Code](govern-apis-vscode-extension.md)
118+
* [Enable and view platform API catalog in Visual Studio Code](enable-platform-api-catalog-vscode-extension.md)
119+

‎articles/api-center/govern-apis-vscode-extension.md

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
title: Govern APIs - Azure API Center - VS Code extension
3+
description: API developers can use the Azure API Center extension for Visual Studio Code to govern their organization's APIs.
4+
author: dlepow
5+
ms.service: azure-api-center
6+
ms.topic: how-to
7+
ms.date: 09/23/2024
8+
ms.author: danlep
9+
ms.custom:
10+
# Customer intent: As an API developer, I want to use my Visual Studio Code environment to govern APIs in my organization's API center.
11+
---
12+
13+
# Govern APIs with the Azure API Center extension for Visual Studio Code
14+
15+
To maximize success of your API governance efforts, it's critical to shift-left governance early into the API development cycle. This approach allows developers to create APIs correctly from the beginning, saving them from wasted development effort mitigating non-compliant APIs later in the development process. API Center's Visual Studio Code experience includes critical capabilities for API developers including:
16+
17+
* Evaluating API designs against API style guides as the API is developed in Visual Studio Code.
18+
* Early detection of breaking changes ensures that APIs remain reliable and function as expected, preserving the trust of end-users and stakeholders.
19+
20+
[!INCLUDE [vscode-extension-basic-prerequisites](includes/vscode-extension-basic-prerequisites.md)]
21+
22+
The following Visual Studio Code extensions are optional and needed only for certain scenarios as indicated:
23+
24+
* [Spectral extension](https://marketplace.visualstudio.com/items?itemName=stoplight.spectral) - to run shift-left API design conformance checks in Visual Studio Code
25+
* [Optic CLI](https://github.com/opticdev/optic) - to detect breaking changes between API specification documents
26+
27+
[!INCLUDE [vscode-extension-setup](includes/vscode-extension-setup.md)]
28+
29+
## API design conformance
30+
31+
To ensure design conformance with organizational standards as you build APIs, the Azure API Center extension for Visual Studio Code provides integrated support for API specification linting with Spectral.
32+
33+
1. Use the **Ctrl+Shift+P** keyboard shortcut to open the Command Palette. Type **Azure API Center: Set active API Style Guide** and hit **Enter**.
34+
2. Select one of the default rules provided, or, if your organization has a style guide already available, use **Select Local File** or **Input Remote URL** to specify the active ruleset in Visual Studio Code. Hit **Enter**.
35+
36+
Once an active API style guide is set, opening any OpenAPI or AsyncAPI-based specification file will trigger a local linting operation in Visual Studio Code. Results are displayed both inline in the editor, as well as in the Problems window (**View** > **Problems** or **Ctrl+Shift+M**).
37+
38+
:::image type="content" source="media/build-register-apis-vscode-extension/local-linting.png" alt-text="Screenshot of local-linting in Visual Studio Code." lightbox="media/build-register-apis-vscode-extension/local-linting.png":::
39+
40+
## Breaking change detection
41+
42+
When introducing new versions of your API, it's important to ensure that changes introduced do not break API consumers on previous versions of your API. The Azure API Center extension for Visual Studio Code makes this easy with breaking change detection for OpenAPI specification documents powered by Optic.
43+
44+
1. Use the **Ctrl+Shift+P** keyboard shortcut to open the Command Palette. Type **Azure API Center: Detect Breaking Change** and hit **Enter**.
45+
2. Select the first API specification document to compare. Valid options include API specifications found in your API center, a local file, or the active editor in Visual Studio Code.
46+
3. Select the second API specification document to compare. Valid options include API specifications found in your API center, a local file, or the active editor in Visual Studio Code.
47+
48+
Visual Studio Code will open a diff view between the two API specifications. Any breaking changes are displayed both inline in the editor, as well as in the Problems window (**View** > **Problems** or **Ctrl+Shift+M**).
49+
50+
:::image type="content" source="media/build-register-apis-vscode-extension/breaking-changes.png" alt-text="Screenshot of breaking changes detected in Visual Studio Code." lightbox="media/build-register-apis-vscode-extension/breaking-changes.png":::
51+
52+
53+
## Related content
54+
55+
* [Azure API Center - key concepts](key-concepts.md)
56+
* [Build and register APIs with the Azure API Center extension for Visual Studio Code](build-register-apis-vscode-extension.md)
57+
* [Discover and consume APIs with the Azure API Center extension for Visual Studio Code](discover-apis-vscode-extension.md)
58+
* [Enable and view platform API catalog in Visual Studio Code](enable-platform-api-catalog-vscode-extension.md)
59+

‎articles/api-center/media/build-register-apis-vscode-extension.md

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
title: Build and register APIs - Azure API Center - VS Code extension
3+
description: API developers can use the Azure API Center extension for Visual Studio Code to build and register APIs in their organization's API center.
4+
author: dlepow
5+
ms.service: azure-api-center
6+
ms.topic: how-to
7+
ms.date: 10/02/2024
8+
ms.author: danlep
9+
ms.custom:
10+
# Customer intent: As an API developer, I want to use my Visual Studio Code environment to register APIs in my organization's API center as part of my development workflow.
11+
---
12+
13+
# Build and register APIs with the Azure API Center extension for Visual Studio Code
14+
15+
API developers in your organization can build and register APIs in your [API center](overview.md) inventory by using the Azure API Center extension for Visual Studio Code. API developers can:
16+
17+
* 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.
18+
* Generate OpenAPI specification files from API code using GitHub Copilot, and register the API to an API center.
19+
20+
[!INCLUDE [vscode-extension-basic-prerequisites](includes/vscode-extension-basic-prerequisites.md)]
21+
22+
The following Visual Studio Code extensions is optional and needed only for the specified scenario:
23+
24+
* [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) - to generate OpenAPI specification files from API code
25+
26+
[!INCLUDE [vscode-extension-setup](includes/vscode-extension-setup.md)]
27+
28+
## Register an API - step by step
29+
30+
The following steps register an API in your API center as a one-time operation.
31+
32+
1. Use the **Ctrl+Shift+P** keyboard shortcut to open the Command Palette. Type **Azure API Center: Register API** and hit **Enter**.
33+
1. Select **Manual**.
34+
1. Select the API center to register APIs with.
35+
1. Answer prompts with information including API title, type, version title, version lifecycle, definition title, specification name, and definition file to complete API registration.
36+
37+
The API is added to your API center inventory.
38+
39+
## Register APIs - CI/CD pipeline
40+
41+
The following steps register an API in your API center with a CI/CD pipeline. 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.
42+
43+
1. Use the **Ctrl+Shift+P** keyboard shortcut to open the Command Palette. Type **Azure API Center: Register API** and hit **Enter**.
44+
1. Select **CI/CD**.
45+
1. adds 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.
46+
1. 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 Azure Pipeline/GitHub Action environment variables and identity. On push to source control, the API will be registered in your API center.
47+
48+
Learn more about setting up a [GitHub Actions workflow](register-apis-github-actions.md) to register APIs with your API center.
49+
50+
## Generate OpenAPI specification file from API code
51+
52+
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**. This will create an OpenAPI specification file.
53+
54+
> [!NOTE]
55+
> This feature is available in the pre-release version of the API Center extension.
56+
57+
:::image type="content" source="media/build-register-apis-vscode-extension/generate-api-documentation.gif" alt-text="Animation showing how to use GitHub Copilot to generate an OpenAPI spec from code." lightbox="media/build-register-apis-vscode-extension/generate-api-documentation.gif":::
58+
59+
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.
60+
61+
62+
## Related content
63+
64+
* [Azure API Center - key concepts](key-concepts.md)
65+
* [Discover and consume APIs with the Azure API Center extension for Visual Studio Code](discover-apis-vscode-extension.md)
66+
* [Govern APIs with the Azure API Center extension for Visual Studio Code](govern-apis-vscode-extension.md)
67+
* [Enable and view platform API catalog in Visual Studio Code](enable-platform-api-catalog-vscode-extension.md)
68+

0 commit comments

Comments
 (0)