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

港控/mmm° 2024-03-16 10:28 51阅读 0赞

#### 前言 ####

在进行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。

#### 总结 ####

swagger-codegen是一个非常方便的API代码生成工具，可以帮助我们快速生成符合规范的API客户端和服务端代码。使用swagger-codegen可以大大提高API开发的效率，减少开发者的工作量。希望本文对大家有所帮助。