What Is OpenAPI?

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.

API specifications can be written in YAML or JSON. The format is easy to learn and readable to both humans and machines. The complete OpenAPI Specification can be found on GitHub: OpenAPI 3.0 Specification

What Is Swagger?

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.