1 / 53
1
2
3
4

OpenAPI

or the specification formerly known as Swagger
5

6
7
8
9
10
11
12

OpenAPI

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.

When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.









https://github.com/OAI/OpenAPI-Specification/

13

Code

14
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.
15
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.
16
paths:

  /pets:
    get:
      summary: List all pets
      #...
    post:
      summary: Create a pet
      #...

  /pets/{petId}:
    get:
      summary: Info for a specific pet
      #...
17
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
      
      # description
      # requestBody
      # security
      # ...

      responses:
        #...
18
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"
19
components:

  schemas:
    Pet:
    Pets:

  responses:
    ErrorResponse:

  requestBodies:
    NewPet:

  headers:
    Limit:
    Offset:
    Pagination:
20
components:

  schemas:

    Pet:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        image:
          type: string
        tag:
          type: string
      required:
        - id
        - name

    Pets:
      type: array
      items:
        $ref: "#/components/schemas/Pet"
21

Workflows

22

Code first

23

Code first

24

Design first

25

Design first

OpenAPI document = single source of truth

Entire team can be involved in developing the communication layer.

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

Tools

27
28
29

Documentation

30

Documentation

  • Generate entire API documentation
  • Less technical representation

Tools:

  • Swagger UI
  • ReDoc
  • Elements (by Stoplight)
31

Code generation

32

Code generation

33

Code generation

openapi.toolsList of OpenAPI code generators
openapi-generator.techJava-based generator for dozens of programming languages
(Docker image available)
openapi-typescript-codegenTypeScript-based generator
34
35

Mocking

36

Mocking

  • Develop against non-existing dependency
  • Parallel development
  • Independence
37

Mocking

Prism (by Stoplight) turns OpenAPI files into a API server.

  • Mocking
    • Random data
    • Examples
  • Data transformations
  • Input / output validations
  • …
38
# https://petstore.com/openapi.yaml
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
                    tag:
                      type: string
39
# https://petstore.com/openapi.yaml
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
                    tag:
                      type: string
40

# Start Prism
prism mock -d https://petstore.com/openapi.yaml

# OR run Prism in Docker
# docker run --init -p 4010:4010 stoplight/prism:4 mock -d -h 0.0.0.0 https://petstore.com/openapi.yaml

[0:00:00 PM] › [CLI] …  awaiting  Starting Prism…
[0:00:00 PM] › [CLI] ℹ  info      GET        http://127.0.0.1:4010/pets
[0:00:00 PM] › [CLI] ℹ  info      POST       http://127.0.0.1:4010/pets
[0:00:00 PM] › [CLI] ℹ  info      GET        http://127.0.0.1:4010/pets/lorem
[0:00:00 PM] › [CLI] ▶  start     Prism is listening on http://127.0.0.1:4010
41

# Perform request
curl https://localhost:4010/pets | json_pp
42
[
  {
    "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"
  }
]
43

Mocking

  • Develop against non-existing dependency
  • Parallel development
  • Independence

Prism (by Stoplight)

44

Automation

45

Automation

46

Automation

Versioning
  • git submodules
  • language agnostic dependency management

CI/CD
  • Instant documentation updates
  • API contract style linting

Development environments
  • SDK generation at startup
  • Mocking server auto-update
47
OpenAPI doc as Single Source Truth
+
automation
=
happy teams
48

Demo

49

#TIL

OpenAPI specification
  • Contract between services
  • Unified way of describing a REST API
  • Code first
  • Design first
Tools
  • Documentation generation
  • SDK generation
  • Mocking servers
  • Automation
Results
  • Single source of truth
  • Enhances workflow
  • Increases independence
50

mrtnvh.com

iodigital.com

51
52
53