Debian上Swagger代码生成器如何使用 - 问答

1. 安装必要工具
在Debian上使用Swagger Codegen前，需安装Java运行环境（JDK 8+）、构建工具（Maven/Gradle，可选但推荐）及Swagger Codegen本身。

安装Java JDK：运行sudo apt update && sudo apt install openjdk-11-jdk，确保java -version显示版本信息。
安装构建工具（可选）：若需将代码生成集成到Maven/Gradle项目中，运行sudo apt install maven或sudo apt install gradle。
安装Swagger Codegen：有两种方式选择：
- 通过pip安装（推荐）：运行pip3 install swagger-codegen，全局可用swagger-codegen命令。
- 下载预编译JAR包：运行wget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.29/swagger-codegen-cli-3.0.29.jar -O swagger-codegen-cli.jar，通过java -jar命令调用。

2. 准备Swagger规范文件
Swagger Codegen依赖**OpenAPI Specification（OAS）**文件（.yaml或.json格式）描述API结构。示例如下：

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List all users
      responses:
        '200':
          description: An array of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string

将上述内容保存为swagger.yaml（或swagger.json），放置在项目目录中。

3. 生成代码
使用Swagger Codegen生成目标语言代码（如Java、Python、JavaScript等），常用参数说明：

-i：输入Swagger规范文件路径（如./swagger.yaml）。
-l：目标编程语言（如java、python、javascript、nodejs-express等）。
-o：输出目录（如./generated-code）。

示例1：生成Java客户端代码（使用pip安装的CLI）

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

示例2：生成Python客户端代码（使用预编译JAR包）

java -jar swagger-codegen-cli.jar generate -i ./swagger.yaml -l python -o ./python-client

示例3：生成Node.js服务器存根（Express框架）

java -jar swagger-codegen-cli.jar generate -i ./swagger.yaml -l nodejs-express -o ./node-server

生成的代码包含API客户端类、模型类、服务器路由等，可直接用于项目开发。

4. 集成到构建流程（可选但推荐）
将Swagger Codegen集成到Maven或Gradle中，实现代码自动生成，避免手动操作。

Maven集成：在pom.xml中添加openapi-generator-maven-plugin插件：

<build>
  <plugins>
    <plugin>
      <groupId>org.openapitools</groupId>
      <artifactId>openapi-generator-maven-plugin</artifactId>
      <version>5.2.1</version>
      <executions>
        <execution>
          <goals>
            <goal>generate</goal>
          </goals>
          <configuration>
            <inputSpec>${project.basedir}/src/main/resources/swagger.yaml</inputSpec>
            <generatorName>java</generatorName>
            <output>${project.build.directory}/generated-sources</output>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

运行mvn generate-sources即可自动生成代码。

Gradle集成：在build.gradle中添加org.openapitools.codegen插件：

plugins {
  id 'org.openapitools.codegen' version '5.2.1'
}
openApiGenerate {
  inputSpec = file("${projectDir}/src/main/resources/swagger.yaml").toString()
  generatorName = 'java'
  outputDir = file("${buildDir}/generated-sources")
}

运行gradle openApiGenerate即可自动生成代码。

5. 验证生成的代码
进入输出目录（如./java-client），检查是否包含以下内容：

API客户端类：如UserApi.java，包含接口方法的实现。
模型类：如User.java，对应Swagger规范中的schemas定义。
配置文件：如pom.xml（Java项目），包含依赖项。

编写简单的测试程序验证代码功能（以Java为例）：

import com.example.client.ApiClient;
import com.example.client.api.UserApi;
import com.example.client.model.User;

public class TestSwaggerCodegen {
  public static void main(String[] args) {
    ApiClient client = new ApiClient();
    UserApi userApi = new UserApi(client);
    // 调用生成的API方法（需根据实际规范调整）
    // List<User> users = userApi.listUsers();
    // System.out.println(users);
  }
}

编译并运行测试程序，确认无报错且能正常调用API。

注意事项

确保Swagger规范文件语法正确（可使用Swagger Editor在线验证）。
生成代码前，根据项目需求调整generatorName（如spring生成Spring Boot服务器存根）。
集成到构建流程时，需确保inputSpec路径正确，避免找不到规范文件。

0 赞

0 踩