OpenAPI has become the industry standard for defining an API, yet it is often treated as a documentation tool only.
Here at RestCase, we are using the OpenAPI specification for supporting and drive many parts of your API lifecycle development because we believe that REST is mostly about a contract between the provider and the consumer of the API. And, if a contract - Then it should be a written contract that many understands.
Here is were OpenAPI specification comes to play!
What is OpenAPI Specification?
The OpenAPI Specification (OAS) and formerly known as Swagger. defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to the source code, documentation, or through network traffic inspection.
When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.
An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate server SDKs and client CDKs in various programming languages, testing tools, and many other use cases.
API Documentation with OpenAPI
Generating documentation for your API is just one of the advantages of defining your API with OpenAPI.
Other benefits include:
- Help different team members develop the API, understand it and agree on its attributes.
- Help external stakeholders understand the API and what they can do with it.
There are many documentation tools you can use in order to visualize your API definitions.
Here are some of the tools available:
LucyBot - Generate a customizable website, with API documentation, console, and interactive workflows, from an OpenAPI spec.
ReDoc - OpenAPI/Swagger-generated API Reference Documentation
WidderShins - Beautiful static documentation for your API.
RapiDoc - Web Component for OpenAPI Spec Viewing. Create beautiful, customizable, interactive API documentation from your OpenAPI Specification.
But OpenAPI is not just about documentation. Let's see other advantages and usages for the OpenAPI definitions and why it is worth to create one for your API.
Design-First Development (Specification-First)
Although you can generate your specification document from code annotations, many say that auto-generation is not the best approach. In Undisturbed REST: A Guide to Designing the Perfect API, Michael Stowe recommends that teams implement the specification by hand and then treat the specification document as a contract that developers use when doing the actual coding. This approach is often referred to as “Design-First Development” or “Documentation Driven API Design”.
With this approach, developers consult the specification document to see what the parameter names should be called, what the responses should be, and so on. After this contract has been established, Stowe says you can then put the annotations in your code to auto-generate the specification document.
Too often, development teams quickly jump to coding the API endpoints, parameters, and responses without doing much user testing or research into whether the API aligns with what users want.
Since versioning APIs is extremely difficult (you have to support each new version going forward with full backward compatibility to previous versions), you want to avoid the “fail fast” approach that is so commonly celebrated with agile.
There’s nothing worse than releasing a new version of your API that invalidates endpoints or parameters used in previous releases.
The design-first approach helps distribute the documentation work to more team members than engineers. Defining the OAS specification before coding also helps teams produce better APIs.
Even before the API has been coded, your spec OAS specification can be used to generate a mock response by different tools available or by adding response definitions within your OAS specification.
There are some very nice Visual OpenAPI Editors you can use in order to speed the development of your API:
ApiBldr - Visual OpenApi Builder - UI Tool For Building API Specification (OpenAPI / Swagger).
Apicurio Studio - A standalone API design studio that can be used to create new or edit existing API designs.
OpenAPI-GUI - GUI / visual editor for creating and editing OpenAPI / Swagger definitions
Mocking a new API
An API specification, like we already went through, is a fantastic tool for early prototyping an API. It helps us define a schema, ways to interact with resources, pretty much all the foundational API ‘things’ we need.
There are plenty of mocking tools out there, because you don’t have to write code, using an API specification can shorten the time for feedback on your new API from days or hours, to several minutes.
Here are some of the API mocking tools there are for OpenAPI:
Connexion - Connexion is a framework on top of Flask that automagically handles HTTP requests defined using OpenAPI (formerly known as Swagger), supporting both v2.0 and v3.0 of the specification. Connexion allows you to write these specifications, then maps the endpoints to your Python functions.
Microcks - Directly import your OpenAPI specification as a Job within Microcks. Then, it directly discovers service definition as well as request/response samples defined as OpenAPI examples. If your specification embeds a JSON or OpenAPI schema definition for your custom datatypes, Microcks will use it for validating received response payload during tests when using the OPENAPISCHEMA strategy.
FakeIt - Create mock server from Openapi specification. It supports randomly generated response, requests validation and more.
APISprout - A simple, quick, cross-platform API mock server that returns examples specified in an API description document. Among the features, it supports OpenAPI 3.x, CORS, Server validation and more.
Implementing an API using Code Generators
If you’re using a spec to get early feedback on your API design, you’re more likely to have a stable API definition when the time comes to implementing it.
In addition to generating documentation, the OpenAPI definition can also be used to accelerate development by scaffolding implementation code and SDKs for the API. It will give you the REST API skeleton project stubs code in many different languages, like Java, Scala, and others and will allow you to save valuable time.
Here are some of the free Code Generators available:
OpenAPI Generator - Generate clients, servers, and documentation from OpenAPI 2.0/3.x documents
GuardRail - Principled code generation from OpenAPI specifications
Swagger-Codegen - Contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition.
API Testing
Once you have an OpenAPI definition, you can quickly create tests and validate the API specifications against the backend implementation of the same API.
The OpenAPI definition provides a contract that describes what a successful response will look like when someone calls your API. This contract can also be re-purposed to generate test cases which can drastically decrease the amount of setup team needed for testing your APIs.
If you create your REST-API contract-first without using any type of generation, you have to make sure that specification and implementation don't diverge.
Here are some of the tools one can use in order to quickly execute API request and validate responses on the fly:
OpenAPI-Validator - Validate data against OpenAPI v3 specification.
Hikaku - A library that tests if the implementation of a REST-API meets its specification. The aim of this project is to meet this need and offer a mechanism to check specification and implementation for equality without having to create requests which are fired against a mock server. So this library won't check the behavior of the API, but the structural correctness.
Dredd - Dredd is a language-agnostic command-line tool for validating API description document against backend implementation of the API.
Summary
I have shown that OpenAPI is not only documentation. The OpenAPI Specification has a whole world of uses and if used correctly it can be a huge asset! With it, you can leverage your API to generate client and server code, do automated testing and much much more!
Want to take your API to the next level? Then you should give your API an OpenAPI specification!