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.
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:
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.
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.
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
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:
Please reach out to the development team on GitHub by reviewing community issues for answers, or by opening a new issue with your question.