OpenAPI Document Tools

The OpenAPI Document Tools extension for Visual Studio Team Services (VSTS) adds a task to auto-generate OpenAPI documents at build time based on your source code + API annotations.

Features

Build Task: Create OpenAPI documents

Teams may leverage this task to auto-generate an OpenAPI document based on Visual Studio XML annotations and assemblies resulting from a build.

To get started annotating your APIs in source code, please read the following wiki articles:

• C# comment tag reference: A tag-by-tag guide for documenting source code
• C# comment samples: Samples showing how-to annotate source code
• Advanced features: An overview & how-to guide of advanced, optional features to control built document's content

Windows Agents

A special note when running this task on a Windows agent. If your service assemblies target framework .NET Core, then PowerShell Core must be used at task runtime. The task will attempt to use PowerShell Core by default, but falls back to using PowerShell unless the Advanced option to disable this behavior is configured. In the event PowerShell is used in conjunction with .NET Core target framework assemblies, you will see errors generating the OpenAPI document related to type load exceptions.

Task Input

Task Output

The following files will be written to your build location in UTF-8 encoding and without a byte order mark (BOM). Please see OpenAPI.NET.CSharpAnnotations for a definition of terms variant and title.

1. An OpenAPI document per variant.

                      File Name Pattern    
   Full document:     OpenApiDocument.{openApiSpecVersion}.{format}
   Variant document:  OpenApiDocument.{openApiSpecVersion}.{title}.{format}
   

2. A metadata document per variant. These metadata files map 1:1 with an OpenAPI document above as hinted by their names.

                      File Name Pattern    
   Full document:     OpenApiDocument.{openApiSpecVersion}.VariantInfo.json
   Variant document:  OpenApiDocument.{openApiSpecVersion}.{title}.VariantInfo.json
   

3. A file containing OpenAPI document generation errors. Note, this document will not exist unless there is at least one error as a result of generation.

   File name pattern: OpenApiDocument.{openApiSpecVersion}.BuildErrors.txt
   

Release Task: Publish OpenAPI documents

Teams may leverage this task to publish OpenAPI documents to VSTS Git source control.

The task will create an intermediate branch containing your target OpenAPI document adds/edits and a corresponding pull request to merge them into a target branch. The task does not push directly into the target branch for two reasons: (1) branch policies may be in place preventing direct pushes, and (2) promotes reviews of changes before they're merged.

An access token with vso.code_manage scope will be required, so the task may create a private branch, push changes, and create a pull request in your repository.

The OpenAPI document file names committed are based on the Title within the document's Info object and have an extension reflecting the content's format (JSON or YAML).

Supported OpenAPI document sources:

1. C# Annotations Generator - Use this option in conjunction with the build task documented above. Note, the release task must be configured to download artifacts, so it has access to the OpenAPI documents from your build output.

2. Git Source Control - Use this option to fetch an OpenAPI document committed to a Git repository.

3. Web Service API - Use this option to fetch an OpenAPI document from a web service GET endpoint. For example, if your document is produced by Swashbuckle. We recommend configuring this task to execute after your service has been deployed, in order to keep documentation up-to-date with your live service.

Task Input

Get Help

Please reach out to the development team on GitHub by reviewing community issues for answers, or by opening a new issue with your question.