一个大的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