The OpenAPI Specification
As the name suggests, the OpenAPI Specification (OAS) is driven by an open source community that's focused on the OpenAPI Initiative within the Linux Foundation Collaborative Project.
In a few words, the OpenAPI Specification is a language-agnostic interface that was designed for REST APIs and allows consumers to discover the capabilities of a service without even knowing what code base is being used to implement the API. The API may not even be ready to use or have a single line of code written. The main reason for this is mentioned in the documentation provided by OpenAPI. Once you have an OpenAPI Specification for your API, it is easy to add the Swagger UI to the project as an interactive communication tool.
Swagger is a project that's composed of tools that help the developers of REST APIs in tasks such as the following:
- API modeling
- Generating API documentation (readable)
- Generating client and server code, with support for various programming languages
In addition to OpenAPI, Swagger provides an ecosystem of tools to help developers when they're designing a new API or maintaining an existing one . Some of these tools are as follows:
- Swagger Editor—for creating a contract:
- Swagger UI—for publishing documentation:
- Swagger Codegen—for generating the skeletons of servers:
In a few words, OpenAPI describes APIs that could be represented in either YAML or JSON formats.
At the time of writing this book, OpenAPI is on Version 3. It is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
The following sections will walk you through how to get started with OpenAPI with Swagger.