Getting started

Install

[dependencies]
openapi-trait = "1"

# For servers:
axum = "0.8"
tokio = { version = "1", features = ["full"] }

The reqwest-client feature is on by default. See Crates and features for the full list.

The example spec

The chapters in this guide use a small spec with three operations:

Operation	Method and path	Auth
`listPets`	`GET /pets?limit=`	none
`createPet`	`POST /pets`	bearer
`getPet`	`GET /pets/{petId}`	bearer

Show pets.openapi.yaml

openapi: 3.0.3
info:
  title: Pets
  version: 1.0.0
  description: Minimal spec used by the examples and the guide.
security:
  - bearerAuth: []
paths:
  /pets:
    get:
      operationId: listPets
      security: []
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            format: int32
      responses:
        "200":
          description: All pets, up to `limit`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
    post:
      operationId: createPet
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewPet'
      responses:
        "201":
          description: The created pet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        "401":
          description: Missing or invalid token.
  /pets/{petId}:
    get:
      operationId: getPet
      parameters:
        - name: petId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: The pet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        "404":
          description: No pet with that id.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    PetStatus:
      type: string
      enum: [available, pending, sold]
    NewPet:
      type: object
      required: [name]
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 64
        status:
          $ref: '#/components/schemas/PetStatus'
    Pet:
      type: object
      required: [id, name]
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
        name:
          type: string
          minLength: 1
          maxLength: 64
        status:
          $ref: '#/components/schemas/PetStatus'

Apply the macro

Put the attribute on an empty module:

#[openapi_trait::axum("examples/pets.openapi.yaml")]
pub mod pets {}

The path is relative to your crate root (CARGO_MANIFEST_DIR), not to the source file.
The spec is tracked by Cargo. Editing the YAML recompiles the crate.
YAML and JSON specs are both accepted.
Every operation needs an operationId. It becomes the method name (getPet → get_pet).
Want F12 to open the generated code? Add source_file: #[openapi_trait::axum("pets.openapi.yaml", source_file)]. See Go-to-definition in your IDE.

Names come from the module

Trait names come from the module name in PascalCase:

Module	Server trait	Client trait	Client auth state
`mod pets {}`	`pets::PetsApi`	`pets::PetsClient`	`pets::PetsAuthState`
`mod petstore {}`	`petstore::PetstoreApi`	`petstore::PetstoreClient`	`petstore::PetstoreAuthState`

Types inside the module are named after the spec: components/schemas/Pet becomes pets::Pet, and operation getPet becomes pets::get_pet::Request and pets::get_pet::Response.

Next steps

Implement a server with axum.
Write a client, either by hand or with the generated reqwest implementation.