openapi:
           # Specification version
        
        info:
           # General API metadata
        
        servers:
           # Server information. BaseURLs, environments, ...
        
        paths:
           # Available paths & operations
        
        components:
           # Datamodel abstraction
        
        security:
           # Security mechanisms can be used across the API
        
        tags:
           # Grouping of paths & components
        
        external docs:
           # Additional external documentation
        
        webhooks:
           # Webhook operations, similar to paths, only API is now a consumer.
        
        

        paths:
        
          /pets:
            get:
              summary: List all pets
              #...
            post:
              summary: Create a pet
              #...
        
          /pets/{petId}:
            get:
              summary: Info for a specific pet
              #...
        
        

        paths:
          /pets:
            get:
              summary: List all pets
              operationId: listPets
              tags:
                - pets
              parameters:
                - name: limit
                  in: query
                  description: How many items to return at one time
                  required: false
                  schema:
                    type: integer
                    format: int32
              responses:
                #...
        
              # description
              # requestBody
              # externalDocs
              # deprecated
              # security
              # servers
              # ...
        

        paths:
          /pets:
            get:
              #...
              responses:
                '200':
                  description: Expected response to a valid request
                  content:
                    application/json:
                      schema:
                        $ref: "#/components/schemas/Pets"
                default:
                  description: unexpected error
                  content:
                    application/json:
                      schema:
                        $ref: "#/components/schemas/Error"
        

        components:
          schemas:
            Pet:
            Pets:
        
          responses:
            ErrorResponse:
        
          requestBodies:
            NewPet:
        
          headers:
            Limit:
            Offset:
            Pagination:
        
          #...
        

        components:
          schemas:
            Pet:
              type: object
              properties:
                id:
                  type: integer
                  format: int64
                name:
                  type: string
                  x-custom-extension: name.firstName
                image:
                  type: string
                tag:
                  type: string
              required:
                - id
                - name
        
            Pets:
              type: array
              items:
                $ref: "#/components/schemas/Pet"
        

Code first

Code first

Generate OpenAPI document from API framework

Design first

Design first

OpenAPI doc = single source of truth

Entire team can be involved in developing the communication layer.

• Providers
• Consumers
• Project owner: future implementation, roadmap considerations

Documentation

Generate entire API documentation

Less technical representation

Tools:

• Swagger UI
• ReDoc
• Elements (by Stoplight)

Linting

Quality assurance for OpenAPI documents

• Validations
• Formatting

Benefits

• Reduce decision-making
• Creates consistency

Spectral (by Stoplight)

SDK Generation

SDK Generation

SDK Generation

SDK Generation

• openapi.tools
      List of OpenAPI SDK generators
• openapi-generator.tech
      Java-based generator for dozens of programming languages
• openapi-typescript-codegen

Mocking

Turn OpenAPI files into a API servers with mocking, transformations, validations, ...

        # ...
        paths:
          /pets:
            get:
              operationId: listPets
              responses:
                "200":
                  content:
                    application/json:
                      schema:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              format: int64
                            name:
                              type: string
        # ...
        

Prism (by Stoplight)

Mocking

Turn OpenAPI files into a API servers with mocking, transformations, validations, ...

        [
          {
            "id": 7094252654184530000,
            "name": "proident consequat anim est elit",
            "tag": "eiu"
          },
          {
            "id": 2067454767236280300,
            "name": "nostrud cupidatat nisi f",
            "tag": "sed eiusmod"
          },
          {
            "id": 5983151522463482000,
            "name": "dolore id minim magna",
            "tag": "aute consectetur do"
          }
        ]
        

Prism (by Stoplight)

Automation

OpenAPI doc = Single Source Truth

• Quality assurance on Pull or Merge request
• Instant documentation updates
• SDK generation at new release/commit
• Mocking server updates

TIL