OpenAPI

OpenAPI is a wonderful project to create APIs or generate API documentation. You will define a specification, and you will be able to generate the server code in many languages (ex: node server).

Many API specifications are available here.


✨ Useful References ✨

Base template for an OAS3 (OpenAPI Specification Version 3) in YAML

openapi: 3.0.3
info:
  title: API NAME
  description: >
    API DESCRIPTION. You can use Markdown.
  version: 1.0.0
servers:
  - url: 'http://localhost:3000'
paths:
  # Add your paths here

🚀 Generation 🚀

API Server-side code

To generate a server from a specification, you can use the OpenAPI Generator (16.9k ⭐). See Install.

# ex: generate nodejs-express-server inside gen from xxx.yaml
$ java -jar openapi-generator-cli.jar generate -g nodejs-express-server -i xxx.yaml -o gen

In PHPStorm, everything is already set up for you, you even got schema verification. See OpenAPI.

Documentation

I haven't tested other tools, but with the popular Redoc (20.4k ⭐) you simply have to

  • Copy the following HTML to your web server
  • Replace the URL with the link to your YAML file

And you're done. See Redoc quick start.

🪵 Schema 🪵

A schema is a definition of something. It's pretty much like a class in oriented-object programming. 7 types are supported which are string, array, object, boolean, integer, number, and null.

String example

schema:
  type: string

Array example

schema:
  type: array
  # type of one element
  items: # a schema
    - type: string

String (enum)

schema:
  type: string
  enum: [value1, value2, value3]

Object example

{
    "username": "toto",
    "age": 0
}

Give us the schema:

schema:
  type: object
  properties:
    username: # a schema
      type: string
    age: # a schema
      type: integer

Schema attributes

Schemas have more attributes than just a type if you need them.

schema:
  type: string
  format: email

schema:
  type: array
  uniqueItems: true
  minItems: 0
  maxItems: 5

schema:
  type: xxx
  readOnly: true # GET only
  writeOnly: true # POST/... only
  description: desc
  example: "1" # example for a string

schema:
  type: integer
  format: int64
  minimum: 0

schema:
  type: object
  additionalProperties: true
  minProperties: 0
  maxProperties: 4
  required:
    - id

Schema references

You may want to avoid copy-pasting the same schema. You can store them in a section components (above "paths:" for me)

components:
  schemas:
    ProductIdParameter:
      type: string
      example: "1"

In the code, you will use $ref

schema:
  $ref: '#/components/schemas/ProductIdParameter'

🛣️ Paths 🛣️

Given http://localhost:3000/products, if the endpoint is http://localhost:3000, then /products is a path of your API.

paths:
  /products:
    get: # post, put, patch, delete
      summary: 'Get the list of products'
      description: 'An optional description'
      responses:
        # see responses

A path can accept multiple methods.

paths:
  /products:
    get:
      # ...
    post:
      # ...

And a path can be made of dynamic parameters

paths:
  /products/{id}:
    get:
      parameters:
        - in: path
          name: id
          required: true
          description: A description
          schema: # see schema

Other notes

paths:
  /some/route:
    get:
      # deprecate a method
      deprecated: true
      # practical use ???
      operationId: some-id

📦 Content 📦

Another block always seen in many responses, bodies, or parameters is content.

The "content" is a set of content-types (ex: JSON) with their associated schema (ex: PersonJSON).

# ex: if you support both JSON and HTML
content:
  application/json:
    schema:
      # insert your schema here
  text/html:
    schema:
      # ...

Requests

Parameters

A query is a parameter in the URL. This is usually used in a GET request "parameters" section.

paths:
  /some/route:
    get:
      parameters:
        # ex: /user?id=some_value
        - in: query
          name: id
          required: true
          description: A description
          schema: # see schema

You could also request a cookie inside parameters.

        # ex: cookie
        - in: cookie
          name: cookie.sid
          schema:
            type: string

Body

Mostly for POST/PATCH/PUT requests.

paths:
  /some/route:
    post:
      requestBody:
        required: true
        content: # see content

👻 To-do 👻

Stuff that I found, but never read/used yet.

Stuff

  • oneOf, anyOf, not
  • Check out how to generate code samples