Go.spec.goからOpenAPI specの出力実験

はじめに

OpenAPI spec書くのきついよね。
ソースで書きたいじゃん。
ということで、実際にやってみた。

input

package api

type Error struct {
    Code    int32
    Message string
}

type NewPet struct {
    Name string
    Tag  string
}

type Pet struct {
    NewPet
    Id int64
}

type FindPetsParams struct {
    Tags  []string
    Limit int32
}

type Interface interface {
    // (GET /pets)
    FindPets(params FindPetsParams) []Pet

    // (POST /pets)
    AddPet(body Pet) Pet

    // (DELETE /pets/{id})
    DeletePet(id int64)

    // (GET /pets/{id})
    FindPetById(id int64) []Pet
}

command

# 1行jsonで出るから、json2yamlでyamlに.....
$ go run cmd/generate/main.go -i testdata/pet.spec.go | json2yaml

output

components:
  schemas:
    NewPet:
      type: object
      properties:
        Tag:
          type: string
        Name:
          type: string
    Error:
      type: object
      properties:
        Code:
          format: int32
          type: integer
        Message:
          type: string
    FindPetsParams:
      type: object
      properties:
        Limit:
          format: int32
          type: integer
        Tags:
          items:
            type: string
          type: array
    Pet:
      allOf:
      - $ref: '#/components/schemas/NewPet'
      - type: object
        properties:
          Id:
            format: int64
            type: integer
openapi: 3.0.0
info: null
paths:
  /pets:
    post:
      responses:
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
      operationId: AddPet
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
    get:
      responses:
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Pet'
                type: array
      parameters:
      - schema:
          items:
            type: string
          type: array
        in: query
        name: Tags
      - schema:
          format: int32
          type: integer
        in: query
        name: Limit
      operationId: FindPets
  /pets/{id}:
    get:
      responses:
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Pet'
                type: array
      parameters:
      - required: true
        schema:
          format: int64
          type: integer
        in: path
        name: id
      operationId: FindPetById
    delete:
      responses:
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - required: true
        schema:
          format: int64
          type: integer
        in: path
        name: id
      operationId: DeletePet

おまけ

• なんか出力の順が悲しいね......
• yamlでいい感じで出んのかね......
• infoくらいは付け足したいね。

先に、server/clientのソースも出してみよう！