APIs – OpenAPI Specification

OAS building blocks
Image Source: https://dev.to/mikeralphson

The OpenAPI Specification previously known as Swagger specification is a community-driven open specification within the OpenAPI Initiative, a Linux Foundation Collaborative Project.

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for APIs which helps to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic.

Use cases for machine-readable API definition documents include, but are not limited to: interactive documentation; code generation for documentation; and automation of test cases.

OpenAPI specification documents describe an API’s services and are represented in either YAML or JSON formats. These documents may either be produced and served statically or be generated dynamically from an application.

The version of the OpenAPI specification currently as at the time of writing this article is version 3.

There are two well-known processes for developing APIs with OAS:

  • Contract First Approach
    • Define the contract
    • Use an OAI Tool to generate a code skeleton for your APIs, OAI supports many programming languages.
  • Code first / Contract Last Approach
    • Write the code for the APIs in your programming language with annotations
    • Use an OAI Tool to generate the contract

The Contract First Approach can be very useful for collaboration, for example, in a scenario where you are developing APIs for a mobile app developer, the contract is defined first, a mock server and a documentation can be generated from the contract with OAI tools, and then both the API developer and the mobile app developer can work simultaneously on the API actual implementation and API integration using the mock server and documentation respectively.

You can find a list of other OAI tools here

References and More Resources: