Background

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for REST APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.

Oasis is:

Base on Plug's implements, according to the OpenAPI Specification to generate server's router and the all well defined HTTP request handlers, since the OAS defines a detailed collection of data types by JSON Schema Specification, Oasis leverages this and focuses on the types conversion and validation to the parameters of the HTTP request.

• Maintain an OpenAPI Specification document(in YAML or JSON) is the first priority
• Generate the maintainable router and HTTP request handlers code by the defined document
• In general, we do not need to manually write the OpenAPI definitions in Elixir
• Simplify the REST APIs to convert types and validate the parameters of the HTTP request
• More reference and communication to your REST APIs

Add oasis as a dependency to your mix.exs

def deps do
  [
    {:oasis, "~> 0.3"}
  ]
end

Oasis does not cover the full OpenAPI specification, so far the implements contain:

• Components Object
• Paths Object
• Path Item Object
• Operation Object
• Parameter Object
• Request Body Object
• Media Type Object
• Header Object
• Reference Object
• Schema Object
• Security Scheme Object
  • Bearer Authentication, please see Oasis.Plug.BearerAuth for details.

We also have some OpenAPI Specification Extensions defined for use, please see our Specification Extensions Guide.

First, write your API document refer the OpenAPI Specification(see reference for details), we build Oasis with the version 3.1.0 of the OAS, as usual, the common use case should be covered for the version 3.0.* of the OAS.

Here is a minimum specification for an example in YAML, we save it as "petstore-mini.yaml" in this tutorial.

openapi: "3.1.0"
info:
  title: Petstore Mini
paths:
  /pets:
    get:
      parameters:
        - name: tags
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
        - name: limit
          in: query
          requried: false
          schema:
            type: integer
            format: int32
      response:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
    post:
      operationId: addPet
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewPet'
      response:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'

  /pets/{id}:
    get:
      operationId: find pet by id
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      response:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      allOf:
        - $ref: '#/components/schemas/NewPet'
        - type: object
          required:
          - id
          properties:
            id:
              type: integer
              format: int64

    NewPet:
      type: object
      required:
        - name
      properties:
        name:
          type: