swagger-codegen的使用方法及常见参数配置

前言

在进行API开发时，我们通常需要定义API的接口规范和文档，以方便其他开发者调用和使用。Swagger是一款非常流行的API文档生成工具，它可以帮助我们快速生成API接口文档，并提供了许多便捷的功能。本文将介绍如何使用swagger-codegen来生成API接口文档。

简介

swagger-codegen是Swagger官方提供的一个代码生成工具，它可以根据Swagger规范文件生成各种语言的API客户端和服务端代码。swagger-codegen支持的语言包括Java、Python、Go、Ruby等多种语言，可以方便地生成符合规范的API代码。

安装

使用swagger-codegen需要先安装它，可以通过以下命令来安装：

npm install -g swagger-codegen

使用

安装完成后，我们可以通过以下命令来生成API客户端或服务端代码：

swagger-codegen generate -i <input-file> -l <language> -o <output-directory>

其中，为Swagger规范文件的路径，为要生成的代码的语言，为输出目录。例如，要生成Java客户端代码，可以使用以下命令：

swagger-codegen generate -i swagger.json -l java -o ./client

这条命令会根据swagger.json文件生成Java客户端代码，并将代码保存到./client目录下。

除了生成客户端代码外，swagger-codegen还支持生成服务端代码。要生成服务端代码，可以使用以下命令：

swagger-codegen generate -i swagger.json -l <language> -o ./server

其中，为要生成的服务端代码的语言，例如Java、Python等。

2. 常见参数配置

2.1 指定生成的API客户端库

使用-l参数可以指定生成的API客户端库的语言。例如，要生成Java客户端库，可以使用以下命令：

java -jar swagger-codegen-cli.jar generate -i http://petstore.swagger.io/v2/swagger.json -l java -o /path/to/output/directory

2.2 指定生成的服务器端代码

使用-l参数可以指定生成的服务器端代码的语言。例如，要生成Node.js服务器端代码，可以使用以下命令：

java -jar swagger-codegen-cli.jar generate -i http://petstore.swagger.io/v2/swagger.json -l nodejs-server -o /path/to/output/directory

2.3 指定生成的API文档格式

使用-l参数可以指定生成的API文档的格式。例如，要生成HTML格式的API文档，可以使用以下命令：

java -jar swagger-codegen-cli.jar generate -i http://petstore.swagger.io/v2/swagger.json -l html -o /path/to/output/directory

2.4 指定生成的API代码包名/命名空间

使用--api-package参数可以指定生成的API代码的包名或命名空间。例如，要将生成的Java API代码放在com.example.api包下，可以使用以下命令：

java -jar swagger-codegen-cli.jar generate -i http://petstore.swagger.io/v2/swagger.json -l java --api-package com.example.api -o /path/to/output/directory

2.5 指定生成的模型代码包名/命名空间

使用--model-package参数可以指定生成的模型代码的包名或命名空间。例如，要将生成的Java模型代码放在com.example.model包下，可以使用以下命令：

java -jar swagger-codegen-cli.jar generate -i http://petstore.swagger.io/v2/swagger.json -l java --model-package com.example.model -o /path/to/output/directory

2.6 指定生成的API接口前缀

使用--api-package参数可以指定生成的API接口的前缀。例如，要将生成的Node.js API接口前缀设置为/api/v1，可以使用以下命令：

java -jar swagger-codegen-cli.jar generate -i http://petstore.swagger.io/v2/swagger.json -l nodejs-server --api-package /api/v1 -o /path/to/output/directory

类名

我们可以通过配置参数来指定生成的类的名称。默认情况下，类名是根据API的路径和操作名称生成的。例如，对于路径为/pet，操作名称为POST的API，生成的类名为PetApi。如果我们想要指定自己的类名，可以使用--api-package参数。例如，我们可以使用以下命令来生成一个名为MyPetApi的类：

swagger-codegen generate -i petstore.yaml -l java -o /path/to/output --api-package com.example.api --model-package com.example.model --api-name MyPetApi

描述

我们可以通过配置参数来指定生成的类的描述。默认情况下，类的描述是从API的description字段中获取的。如果我们想要指定自己的描述，可以使用--api-description参数。例如，我们可以使用以下命令来生成一个类，并指定其描述为This is my API：

swagger-codegen generate -i petstore.yaml -l java -o /path/to/output --api-package com.example.api --model-package com.example.model --api-description "This is my API"

方法名

我们可以通过配置参数来指定生成的方法的名称。默认情况下，方法名是根据操作名称生成的。例如，对于操作名称为createPet的API，生成的方法名为createPet。如果我们想要指定自己的方法名，可以使用--api-name参数。例如，我们可以使用以下命令来生成一个方法，并指定其名称为addPet：

swagger-codegen generate -i petstore.yaml -l java -o /path/to/output --api-package com.example.api --model-package com.example.model --api-name MyPetApi --api-operation-name addPet

配置文件的方式

swagger-codegen 的配置文件是一个 JSON 格式的文件，可以通过 -c 参数指定。下面是一个简单的配置文件示例：

{"packageName": "com.example","description": "This is a sample API","apiPackage": "com.example.api","modelPackage": "com.example.model","modelFiles": {"User": {"description": "A user object","className": "User","template": "User.mustache","importMapping": {"DateTime": "org.joda.time.DateTime"}}}
}

配置文件参数说明

packageName: 生成代码的包名。
description: API 的描述信息。
apiPackage: 生成 API 类的包名。
modelPackage: 生成模型类的包名。
modelFiles: 模型类的配置信息，其中每个键值对表示一个模型类。
- description: 模型类的描述信息。
- className: 模型类的类名。
- template: 模型类的模板文件名。
- importMapping: 模型类中需要导入的类的映射关系。

配置文件的使用

在生成代码时，我们可以通过 -c 参数指定配置文件的路径。例如：

swagger-codegen generate -i swagger.json -l java -c config.json -o output/

这样，swagger-codegen 就会根据配置文件中的参数生成代码。

其他参数

除了上述常见的配置参数外，还有许多其他的参数可以用来控制生成的代码的细节。例如，我们可以使用--model-name-prefix参数来指定生成的模型类的名称前缀，使用--model-name-suffix参数来指定生成的模型类的名称后缀，使用--date-library参数来指定日期类型的库等等。具体的参数可以参考swagger-codegen的官方文档https://swagger.io/tools/swagger-codegen/
https://github.com/swagger-api/swagger-codegen/issues/7795
https://github.com/swagger-api/swagger-codegen#generating-a-client-library。