Getting started with OpenAPI specifications.md

What is an OpenAPI Specification?

OpenAPI Specification (formerly known as Swagger Specification) is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API, including:

• Available endpoints (/users) and operations on each endpoint (GET /users, POST /users)
• Operation parameters input and output for each operation
• Authentication methods
• Contact information, license, terms of use and other information

Currently, we only support OpenAPI Specification 2.0 or Swagger V2.0.

Helpful Resources

• Understanding the GitHub flow
• Microsoft REST-API guidelines]
• Resource Provider Guidelines
• Sample directory structure for swagger
• Structure of a Swagger specification
• Sample Swagger specification
• Sample Readme.md
• Swagger style guide
• Authoring good Swagger descriptions
• Validation tools
  • Validation checks through automated tools
  • Validation checks done manually
  • OAV Validation checks
• Breaking Changes guidelines
• x-ms-examples