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

发表于 | 分类于 |
一个大的OpenAPI Specification yaml 分割成小的yaml文件

前言

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

依赖运行环境: Nodejs, jdk1.8+
在这个文章，将以经典的 PetStore 为列来讲如何将大文件分离到更小的文件中，所以也适用于你自己的定义。

正文

  1. 重复引用定义来自文件
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
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 文件
1
npm install -g swagger-cli
  1. 从swagger-api/swagger-codegen 的说明，下载 swagger-codegen-cli-3.0.20.jar,我目前看到的链接是:
1
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