Paths

Body, response, tags & operations

paths:
  /data:
    post:
      tags:
        - Primitive
      operationId: update
      requestBody:
        description: Request body
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Primitive"
      responses:
        "200":
          description: Default response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Primitive"

Adding a application/json request body and response result in the function as follows:

update : Api.Data.Primitive -> Api.Request Api.Data.Primitive

Using a tag puts the generated request in a module with that name. If you do not use a tag, the Default module is used. Using operationId allows you to set the name of the function. If absent, the function name is created automatically.

Path

paths:
  /path/{string}/{integer}:
    get:
      parameters:
        - name: string
          in: path
          schema:
            type: string
        - name: integer
          in: path
          schema:
            type: integer
      responses:
        "200":
          description: Default response

A path may contain variables. The generator will add them as required parameters to your function.

pathStringIntegerGet : String -> Int -> Api.Request ()

Query

paths:
  /query:
    get:
      parameters:
        - name: string
          in: query
          schema:
            type: string
        - name: int
          in: query
          schema:
            type: integer
        - name: enum
          in: query
          schema:
            type: string
            enum: [a, b, c]
      responses:
        "200":
          description: Default response

You may add query parameters as well.

type Enum
    = EnumA
    | EnumB
    | EnumC


enumVariants =
    [ EnumA
    , EnumB
    , EnumC
    ]


queryGet : Maybe String -> Maybe Int -> Maybe Enum -> Api.Request ()

Headers

paths:
  /header:
    post:
      parameters:
        - name: string
          in: header
          required: true
          schema:
            type: string
        - name: integer
          in: header
          schema:
            type: integer
      responses:
        "200":
          description: Default response
          content:
            application/json:
              schema:
                type: string

OpenAPI also allows you to add headers to each request. Note that one of the headers is required while the other is not.

headerPost : String -> Maybe Int -> Api.Request String

Security

paths:
  /secured:
    post:
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Authenticated
        "401":
          description: Unauthenticated
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

OpenAPI also allows you to add a security scheme to a single or all requests. The Elm generator currently only supports using bearer tokens. This adds an additional String token parameter to the relevant request functions. The request will have an additional Authorization: Bearer <token> header attached.

securedPost : String -> Api.Request ()