一個大的OpenAPI Specification yaml 分割成小的yaml文件

前言

遵循的yaml格式是 swagger 官網的 OAS3 的說明,主要參考文章 How to split a large OpenAPI Specification into multiple files

依賴運行環境: Nodejs, jdk1.8+
在這個文章，將以經典的 PetStore 為列來講如何將大文件分離到更小的文件中，所以也適用於你自己的定義。

正文

1. 重復引用定義來自文件

paths:
  /pets/{petId}:
    get:
      summary: Info for a specific pet
      operationId: showPetById
      parameters:
        - name: petId
          in: path
          required: true
          description: The id of the pet to retrieve
          schema:
            type: string
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                  type: object
                  required:
                    - id
                    - name
                  properties:
                    id:
                      type: integer
                      format: int64
                    name:
                      type: string
                    tag:
                      type: string

依賴

1. 通過npm安裝swagger-cli, 用於將多個 yaml 文件合並為一個 yaml 文件

npm install -g swagger-cli

2. 從swagger-api/swagger-codegen 的說明，下載 swagger-codegen-cli-3.0.20.jar,我目前看到的鏈接是:

https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.20/swagger-codegen-cli-3.0.20.jar

后記

因為自己個人習慣將請求路徑按功能模塊放入到不同的yaml文件中，以方便自己維護api文檔，但這樣也添加了時間成本，因為需要先執行合並yaml文件的命令，然后再將執行將 yaml文件轉換為swagger-ui能識別的json文件的命令

References

• How to split a large OpenAPI Specification into multiple files 主要學習了如何將一個大的yaml文件分離小的yaml文件
• download swagger codegen -cli
• How do I combine multiple OpenAPI 3 specification files together?
• dgarcia360/openapi-boilerplate