openapi: 3.1.0
info:
  title: Novus Example API
  version: 1.0.0
  description: A tiny example API for testing OpenAPI tooling.
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      summary: List users
      operationId: listUsers
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: A page of users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPage'
    post:
      summary: Create a user
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewUser'
      responses:
        '201':
          description: Created
        '422':
          description: Validation failed
  /users/{id}:
    get:
      summary: Get a user
      operationId: getUser
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: A user
        '404':
          description: Not found
components:
  schemas:
    User:
      type: object
      required: [id, name, email]
      properties:
        id: { type: integer }
        name: { type: string }
        email: { type: string, format: email }
        role: { type: string, enum: [admin, member, guest] }
    NewUser:
      type: object
      required: [name, email]
      properties:
        name: { type: string }
        email: { type: string, format: email }
    UserPage:
      type: object
      properties:
        page: { type: integer }
        total: { type: integer }
        items:
          type: array
          items:
            $ref: '#/components/schemas/User'