Inline reference

Yesterday entry shows that when the specs use local references, one solution is to declare two oapi-codegen configs: one for the model, and the other for the server. However, that is hard to maintain. There is another option, which is to convert local references in the spec to internal reference. In the diff below, it shows that earlier, we defined a schemas.yaml file that was locally referenced by the spec; now, it points to the parent spec, which is openapi.yaml

-          $ref: "../components/schemas.yaml#/JournalEntryCreate"
+          $ref: "#/components/schemas/JournalEntryCreate"

To generate the server and model, you just need one command now: go tool oapi-codegen -config openapi/config/codegen.yaml openapi/openapi.yaml

openapi.yaml

openapi: 3.0.3
info:
  title: Journal API
  version: 0.1.0
servers:
  - url: http://localhost:8080
paths:
  /journals:
    $ref: "./paths/journals.yaml"
components:
  schemas:
    JournalEntryCreate:
      type: object
      required:
        - title
        - body
      properties:
        title:
          type: string
        body:
          type: string
    JournalEntry:
      type: object
      required:
        - id
        - title
        - body
        - created_at
        - updated_at
      properties:
        id:
          type: string
        title:
          type: string
        body:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

journals.yaml

post:
  summary: Create a journal
  operationId: CreateJournal
  tags:
    - Journal
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/JournalEntryCreate"
  responses:
    "201":
      description: Created
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/JournalEntry"
`