When I was working as a developer at IBM, I had the opportunity to work with many different API specifications, and I can say that OpenAPI 3 is one of the most powerful and versatile options available. In this blog post, I'll dive into what OpenAPI 3 is, how it works, and provide some examples to help illustrate its capabilities.

OpenAPI 3 is the latest version of the OpenAPI Specification, a standard for describing, producing, consuming, and visualizing RESTful web services. This specification provides a comprehensive set of tools and guidelines for creating and using web services that are both human and machine-readable.

What is OpenAPI 3?

OpenAPI 3 is a specification for building APIs. It is based on the Swagger 2.0 specification, but with significant improvements and updates. The goal of OpenAPI 3 is to provide developers with a standard way to describe APIs, making it easier to both build and consume them. It is a powerful tool for creating, documenting, and sharing RESTful web services. It enables developers to create APIs that are reliable, secure, easy to maintain, and portable across different platforms. OpenAPI 3 is also extensible, meaning that developers can customize certain parts of the specification to better suit their use case.

At its core, the OpenAPI 3 specification is a YAML or JSON file that describes the structure and behaviour of an API. This file contains information about the API's endpoints, parameters, responses, security requirements, and more. With this information, developers can easily build client libraries, test suites, and other tools that can interact with the API.

How does OpenAPI 3 work?

OpenAPI 3 specifications are written in the YAML markup language. This file is broken down into several sections, each of which describes a different aspect of the API. All specifications must include the basic information and components, as well as the tags and servers. Additionally, the paths and security sections must be included, though they can be left empty.

Anatomy of OpenAPI 3 Specifications

OpenAPI 3 specifications consist of seven main components:

1. Info - The info section is the first section of the OpenAPI 3 specification. It provides basic information about the API, such as the title, version, and contact information. This section should also include a description of the API, as well as any external documentation URLs.

2. Servers - The servers section is used to define the URLs and protocols used to access the API. This section must include a URL for each server, as well as the protocol used to access it.

3. Paths - This section describes the resources, operations, and parameters used to access the API. The paths section of the OpenAPI 3 specification describes the various endpoints that make up your API. For each endpoint, you'll define the HTTP method (e.g. GET, POST, PUT, DELETE), the URL path, and any parameters that are accepted.

    paths:
      /pets:
        get:
          summary: Returns a list of pets
          operationId: getPets
          parameters:
            - name: limit
              in: query
              description: The maximum number of pets to return
              required: false
              schema:
                type: integer
          responses:
            '200':
              description: A list of pets
              content:
                application/json:
                  schema:
                    type: array
                    items:
                      $ref: '#/components/schemas/Pet'
   

4. Components - The components section of the OpenAPI 3 specification contains reusable definitions for things like data models, security schemes, and response types.

    components:
      schemas:
        Pet:
          type: object
          properties:
            name:
              type: string
            age:
              type: integer
            breed:
              type: string
   

5. Security - The security section of the OpenAPI 3 specification describes the authentication and authorization mechanisms that are required to access the API.

   Once you've defined your OpenAPI 3 specification, you can use it to generate client libraries, documentation, and other tools using a variety of tools and libraries that support the specification.

    security:
      - api_key: []
   

6. Tags - This section describes the tags used to categorize API operations and simplify API navigation.

7. External Docs - This section contains documentation and links to additional resources related to the API.

Examples of OpenAPI 3

To give you a better sense of what OpenAPI 3 looks like in practice, here are a few examples of different sections you might include in a specification.

Example 1: Basic API definition

This example shows a basic definition of an API using OpenAPI 3. It defines a single endpoint that accepts GET requests at the "/hello" path and returns a simple JSON response.

openapi: 3.0.0
info:
  title: Sample API
  description: A simple API example
  version: 1.0.0
paths:
  /hello:
    get:
      summary: Greet the user
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Hello, world!"

Example 2: Request parameters

This example shows how to define request parameters in an OpenAPI 3 specification. It defines an endpoint that accepts GET requests at the "/user/{id}" path, where "{id}" is a path parameter that specifies the user's ID. It also includes a query parameter that allows clients to specify the format of the response (JSON or XML).

openapi: 3.0.0
info:
  title: User API
  description: API for managing user data
  version: 1.0.0
paths:
  /user/{id}:
    get:
      summary: Get a user by ID
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the user to retrieve
          schema:
            type: integer
        - name: format
          in: query
          required: false
          description: The format of the response (JSON or XML)
          schema:
            type: string
            enum: [json, xml]
            default: json
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
            application/xml:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string

Example 3: Authentication

This example shows how to define authentication requirements in an OpenAPI 3 specification. It defines an endpoint that requires clients to provide an API key in the "X-API-Key" header.

openapi: 3.0.0
info:
  title: Secure API
  description: API that requires authentication
  version: 1.0.0
paths:
  /secure-data:
    get:
      summary: Get secure data
      security:
        - api_key: []
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: string
components:
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: X-API-Key

Conclusion

Using OpenAPI allows us to ensure that your integration is smooth, robust, and fast. Whenever you define a new API you should always prefer using some API schema over hand-writing it.

I found this course on open API quite useful for beginners: Building APIs with Swagger and the OpenAPI Specification