How to describe an API service with openAPI 3.1

What is OpenAPI 3.1?

OpenAPI 3.1 is the latest version of the OpenAPI standard, designed to describe API services based on the HTTP protocol. It allows understanding and consuming an API service without accessing its source code, facilitating the generation of interactive documentation and test automation. It is readable by both humans and computers and is widely used in the industry.

If you’ve already heard about the API-first approach and you recognize the value of planning and describing your API service through a specification file,

then it's undoubtedly the best time to talk about which elements are necessary for this type of document.

To this purpose, let's use the OpenAPI specification standard (OAS) in its latest version: OpenAPI 3.1.

In case you are not familiar with OpenAPI, it is a standard for the description of API services based on the HTTP protocol, which allows you to understand and consume the capabilities of an API service without having access to its source code, additional documentation or having to inspect the network traffic. In addition, OpenAPI is readable by both humans and computers, making the generation of interactive documentation and the automation of test scenarios much easier.

Nowadays, OpenAPI is positioned as the most popular standard in the industry to describe APIs.

That being said, let's get started!

About the specification format in openAPI

JSON o YAML?

First of all, let's make it clear that the specification code based on OAS can be implemented in any of two possible alternatives, JSON or YAML format. Which one of them you use in your code is up to you.

The following examples will be described in YAML format because curly brace characters tend to visually clutter the specification document when there are many nested objects, thus making it difficult to understand the data structure. But once again: it's your decision which format to use!

What must be included in an openAPI specification file?

First, the OpenAPI object, which is the root of the file. This object includes four important properties:

• openapi

• paths

• security

• components

#OpenAPI object

openapi: 3.1.0
info:
  version: '1.0.0'
  title: 'RedsauceBlog REST API'
servers:
  - url: 'localhost:3000'
paths:
  ...
  ...
components:
  ...
  ...
security:
  ...

The openapi property allows you to set the value of the OAS version you are using in your document. Defining the value of this property is non-negotiable since different versions of the OAS standard differ among them in specific aspects, so syntax errors may arise if the version and the structure of the document do not match.

Additionally, you must define values for the info and server properties in the OpenAPI object. The first allows you to set the title and version of the API that is specified. The second allows defining the domain or domains where the service will be deployed. If the latter is not defined or is an empty collection, then it defaults to "/".

1. The routes in openAPI

The paths property is the main part of the document; in other words, it is the "core" of the specification. This property defines all the routes that make up the API which can be concatenated with the base route defined in the server property to build the absolute route.

Suppose we want to create a specification document for an API that is made up of the following operations:

In this example, there are two fundamental paths include in the document: the "/user" and the "/user/:id" routes.

Take into account that each route is specified through an object whose properties include the actions associated with the different operations: get, post, update and delete, among others. Therefore, within each of these operation properties you will be able to detail the headers, request bodies, response types and other elements of each operation that incorporates the route.

Likewise, the parameters of a route, whether they are of the "path" or "query" type, must be specified in the parameters property of this same object in the form of a collection, and it is possible to describe its data schema in this section of the document or in the components property as we will explain later.

Just look at how the specification file would look like for the three operations described in the table and how you should define the “id” parameter of type “path”.

...
paths:
  /user:
    post:
      summary: Create a new user
      operationId: createUser
      responses:
        ...
        ...
  /user/{id}:
    parameters:
      - name: id
        in: path
        description: The user´s id value
        required: true
        schema:
          type: integer
          format: int32
    # one operation for the '/user/:id' path
    get:
      summary: Returns details about a particular user
      operationId: getUser
      responses:
        ...
        ...
    # another operation for the '/user/:id' path
    delete:
      summary: Deletes a particular user
      operationId: deleteUser
      responses:
        ...
        ...

For operations that require sending information in the request body, then it is necessary to specify their data scheme. Continuing with our example API, for the "Create a user" operation it is necessary to send the user's data to the server, at least their name, registration email and password. So, let's see how to define the request body for the post(user/:id) operation:

...
  paths:
    /user:
      post:
        summary: Create a new user
          operationId: createUser
          requestBody:
            schema:
              # request body object
              type: object
              required:
                - email
                - name
                - password
              properties:
                email:
                  type: string
                  format: email
                name:
                  type: string
                pasword:
                  type: string
          responses:
            ...
            ...
    /user/{id}:
        ...

Note that data types and formats declared in each required schema are consistent with the JSON Schema Specification Draft 2020-12 standard. This is one of the updates of the latest version of OpenAPI that differs from the previous versions.

2. A response must be defined in openAPI

At the very least, one successful response and one error response must be included in every operation. Likewise, if information is returned in the response body, it is necessary to specify the media type of the response in one or more of the available alternatives, such as: application/json, text/plain, multipart/form-data, or other.

...
paths:
  /user:
    post:
      summary: Create a new user
      operationId: createUser
      requestBody:
        ...
      responses:
        # a successful response
        '201':
          description: User was successfully created
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                  - name
                properties:
                  id:
                    type: integer
                    format: int64
                  name:
                    type: string
                  tag:
                    type:
                      - string
                      - null
        # an error response
        '400':
          description: Bad request error
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - message
                properties:
                  code:
                    type: integer
                    format: int32
                  message:
                    type: string
        # Respuesta negativa
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - message
                properties:
                  code:
                    type: integer
                    format: int32
                  message:
                    type: string
  /user/{id}:
    ...

Components in openAPI

In the components property you can define all the data schemas, parameters, headers, request bodies, examples, security mechanisms, among other elements that are used throughout the specification document. If you want to explore the full list of options click on the next link.

Let's see how to specify different elements in the components property:

components:
  parameters:
    id:
      name: id
      in: path
      description: Id of the user
      required: true
      schema:
        type: integer
        format: int32
  schemas:
    NewUser:
      type: object
      required:
        - email
        - name
        - password
      properties:
        email:
          type: string
          format: email
        name:
          type: string
        pasword:
          type: string
    User:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type:
            - string
            - null
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
  securitySchemes:
    BearerToken:
      type: http
      scheme: bearer
      bearerFormat: JWT

Each declaration of a particular schema must be started with a descriptive and unique name. Of course, the schemas of each element are different in terms of their properties, so it is necessary to review their composition in the official OAS documentation to avoid errors.

Your best friend: $ref

$ref is undoubtedly your best ally when it comes to reducing complexity and making your specification easier to understand.

With $ref you can reference the definition of an element that is hosted inside or outside of the main specification document by simply using the “local”, “remote” or “external” declarations. Take a look at the syntax for referencing a component at different scopes:

In this way, you can reference the schemas of the elements you define (either in the components object or in a separate file) in each of the corresponding sections of the main specification document.

Taking advantage of the ease of using $ref not only makes your document more visually organized and understandable, but you can also reduce the number of lines by separating the elements into independent files.

Let's see how to use a reference in the schema of a response to an object that has been previously defined in the components.

...
paths:
  ...
  /user/{id}:
    parameters:
      # `id` parameter was defined in components and it is referenced at this line
      - $ref: '#/components/parameters/id'
    get:
      summary: Returns details about a particular user
      operationId: getUser
      responses:
        '200':
        description: Details about a user by id
        content:
          application/json:
            schema:
              # User schema was also defined in components and it is used next
              $ref: '#/components/schemas/User'
        '401':
          description: 'Unauthorized'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      ...

What about security in openAPI?

In general, most API services require one or more security mechanisms for at least one operation. Therefore, it is vital to include the security property of the [OpenAPI object](https://spec.openapis.org/ oas/v3.1.0#openapi-object) in your document and understand its proper use.

The security property allows defining a collection of different security mechanisms (HTTP authentication, API key, mutual TLS, OAuth2, OpenID Connect Discovery) with global scope for all operations.

openapi: 3.1.0
...
security:
  - BearerToken: []
paths:
  /user:
    post:
      summary: Create a new user
      operationId: createUser
      security: []
      requestBody:
        ...
      responses:
        '201':
         ...
        '400':
         ...
        '500':
         ...
  /user/{id}:
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      summary: Returns details about a particular user
      operationId: getUser
      responses:
        '200':
          ...
        '401':
         ...
        '500':
         ...

It’s worth mentioning that these mechanisms must be previously defined in the components property and, additionally, each operation object must include a security property to redefine the collection of mechanisms. So if you need to override or modify the scope of one of them for a particular operation, you just have to redefine its collection.

Also be aware that only one of the security requirements must be met to authorize a request and that in case an operation does not require a security mechanism you must declare its collection as empty.

Don't forget the examples in your openAPI files.

There is no good API specification without examples in its schemas and answers. Examples can be specified either through the examples property available for each schema and response, or as part of the components object. Of course, if you use this second alternative, you must later reference the example in the corresponding section of the document.

Note that the examples property is a collection in OpenAPI version 3.1, so it is necessary to start each example with a hyphen.

 # Example array declared in the inner schema of a random element
...
components:
  parameters:
    id:
      name: id
      in: path
      description: Id of the user
      required: true
      schema:
        type: integer
        format: int32
        examples:
          - 1
          - 2
...

 # Examples previously declared in components object…
...
components:
  parameters:
    ...
  schema:
    ...
  examples:
    BadRequestError:
      value:
        code: 400
        message: Bad Request Error

# …can be referenced later as:
...
  responses:
    ...
    '400':
      description: Bad request error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            $ref: '#/components/examples/BadRequestError'
        '500':
          ...

Examples are absolutely necessary for documentation and simulation environments, so you must never do without them.

And don't forget to take advantage of the summary and description properties, both available for most of the objects defined by the OAS. These two properties are really helpful for describing the relevant issues of an object and they are very useful for the automatic generation of documentation.

You are ready to specify APIs under OpenAPI 3.1!

These are the essential steps to developing an OAS-based API specification document.

A bonus

A good practice is to include the use of tags. This metadata allows you to organize your operations into different groups with related actions, functionalities, types of permissions, or any other shared feature. To put this in practice, you can define a global group of tags in the tags property and then, you must assign each tag property to operations that can be characterized by it.

And now you have everything you need to describe your future APIs under the OpenAPI 3.1!

So, will you use it in your next API description document?