Write the OpenAPI specification (OAS)

Before you start

Get the latest version of your API's repository locally before making changes.

Write the specification

API documentation is generated from an OpenAPI specification (OAS) file. OpenAPI is the standard for specifying RESTful APIs.

Open the specification file

Locate and open the application.yaml file within the API's resources folder.

resources/public/api/conf/1.0/application.yaml

Update the info section

The info section must specify the version number, title, and a short description of your API.

info:
  version: "1.0"
  title: OpenAPI Example
  description: |
    # Overview
    This is an example API that allows software developers to test
    that their applications can connect with the API Platform.

Add security schemes

Define the security schemes in the components section of your application.yaml file. Include the security scheme type, OAuth flow details, and scopes. Only one scope can be applied to any individual endpoint.

components:
  securitySchemes:
    userRestricted:
      type: oauth2
      description: |
        The platform supports OAuth 2.0 for authenticating user-restricted
        API requests using an OAuth 2.0 Bearer Token in the AUTHORIZATION header.
      flows:
        authorizationCode:
          authorizationUrl: https://api.platform.example/oauth/authorize
          tokenUrl: https://api.platform.example/oauth/token
          refreshUrl: https://api.platform.example/oauth/refresh
          scopes:
            hello: access hello user

    applicationRestricted:
      type: oauth2
      description: |
        The platform supports OAuth 2.0 for authenticating application-restricted
        API requests using an OAuth 2.0 Bearer Token in the AUTHORIZATION header.
      flows:
        clientCredentials:
          tokenUrl: https://api.platform.example/oauth/token
          scopes: {}

Document the paths

Document each resource action your API provides. The minimum specification for a path contains the HTTP verb, a summary, a description, and the responses it can return.

paths:
  /<your-API-context>/hello-world:
    get:
      summary: Say hello world
      description: |
        A simple example for integrating with an unrestricted service.
        Any request to this endpoint initiates a 'Hello World' response.
      responses:
        200:
          description: "OK Response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                { "message": "Hello World" }

If your endpoints share common parameters, define these as reusable parameters to avoid repetition and ensure consistency across your API.

Assign access levels

Once you have defined the security schemes and paths, assign access levels to your API endpoint. Then run the API locally to preview the OAS documentation.