What Is OpenAPI and Swagger?

OpenAPI Specification (formerly 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

Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document and consume REST APIs. The major Swagger tools include:

• Swagger Editor – browser-based editor where you can write OpenAPI definitions.
• Swagger UI – renders OpenAPI definitions as interactive documentation.
• Swagger Codegen – generates server stubs and client libraries from an OpenAPI definition.
• Swagger Editor Next (beta) – browser-based editor where you can write and review OpenAPI and AsyncAPI definitions.
• Swagger Core – Java-related libraries for creating, consuming, and working with OpenAPI definitions.
• Swagger Parser – standalone library for parsing OpenAPI definitions
• Swagger APIDom – provides a single, unifying structure for describing APIs across various description languages and serialization formats.

Why Use OpenAPI?

The ability of APIs to describe their own structure is the root of all awesomeness in OpenAPI. Once written, an OpenAPI specification and Swagger tools can drive your API development further in various ways:

• Design-first users: use Swagger Codegen to generate a server stub for your API. The only thing left is to implement the server logic – and your API is ready to go live!
• Use Swagger Codegen to generate client libraries for your API in over 40 languages.
• Use Swagger UI to generate interactive API documentation that lets your users try out the API calls directly in the browser.
• Use the spec to connect API-related tools to your API. For example, import the spec to SoapUI to create automated tests for your API.
• And more! Check out the open-source and commercial tools that integrate with Swagger.

Basic Structure

We can write OpenAPI definitions in YAML or JSON with everything being case-sensitive.

Metadata

Every API definition must include the version of the OpenAPI Specification that this definition is based on:

1. openapi: 3.0.0

The OpenAPI version defines the overall structure of an API definition – what you can document and how you document it. OpenAPI 3.0 uses semantic versioning with a three-part version number. The available versions are 3.0.0, 3.0.1, 3.0.2, and 3.0.3; they are functionally the same.

The info section contains API information: title, description (optional), version:

info:

title: Sample API

description: Optional multiline or single-line description in[CommonMark](http://commonmark.org/help/) or HTML.

version: 0.1.9