OpenAPI

Sample API specification

An annotated OpenAPI 2 spec. Guardrail-specific extensions are documented on extensions.md.

swagger: "2.0"
info:
  title: My Service
  version: 0.1.0
host: localhost:1234
schemes:
  - http
paths:
  /user/{id}:
    get:
      operationId: getUser
      x-jvm-package: users
      parameters:
      - name: id
        in: path
        description: The ID of the user
        required: true
        type: string
        x-scala-type: CustomString
      responses:
        200:
          schema:
            $ref: '#/definitions/User'
        404:
          description: Not found
definitions:
  User:
    type: object
    required:
      - id
      - user_addresses
    properties:
      id:
        type: string
      user_addresses:
        $ref: '#/definitions/UserAddresses'
  UserAddresses:
    type: array
    items:
      $ref: '#/definitions/UserAddress'
  UserAddress:
    type: object
    properties:
      line1:
        type: string
      line2:
        type: string
      line3:
        type: string

operationId becomes the function name. x-jvm-package controls the generated package; the last segment becomes the class name (UsersClient). Required fields stay required; optional fields become Option[T]. Response codes map to constructors such as respond.OK(user).

Continue with Scala or Java setup.