API 仕様とフラグメントの設計

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer

paths:
  /users:
    get:
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

properties:
  age:
    type: integer  # Prefer simple types over complex types like objects

properties:
  status:
    type: string
    enum: [active, inactive]

# Good
properties:
  name:
    type: string
  address:
    type: string

# Avoid
properties:
  user:
    type: object
    properties:
      profile:
        type: object
        properties:
          name:
            type: string

responses:
  '200':
    description: Successful response
    headers:
      X-Rate-Limit-Limit:
        description: The number of requests allowed in the current period
        schema:
          type: integer

Book:
  type: string
  example: "Explain the string with as few words as possible."

Car:
  description: This is a car
  properties:
    brand: string
    model: string
  example:
    brand: Toyota
    model: Corolla
Person:
  properties:
    owns: Car

Person:
  type: Employee | Customer

/basic:
  type: {resourceTypes.fhirResourceType: {
      postExample : !include /examples/requests/post_resource.json,
      getExample  : !include /examples/responses/get_resource.json,
      bundleName : basic.BasicBundle
    }
  }
  /_search:
    get:
      is: [ searchParams ]
    post:
      is: [ POSTSearchParams ]