如何使用 Swagger codegen 开发一个简单的 REST 客户端？

Question

我正在学习 Swagger 以及如何使用 Swagger codegen 生成 REST 客户端。我知道如何用 Swagger 做文档，我也知道如何用 Swagger 生成一个简单的 REST 服务器，但我不知道如何用 Swagger codegen 生成一个简单的 REST 客户端。例如，我有一个简单的应用程序，它是一个 REST 服务器，我想生成 REST 客户端。我可以用 Swagger codegen 做到这一点吗？REST 服务器的控制器：package com.dgs.spring.springbootswagger.controller;import io.swagger.annotations.Api;import io.swagger.annotations.ApiOperation;import io.swagger.annotations.ApiParam;import io.swagger.annotations.ApiResponse;import io.swagger.annotations.ApiResponses;@RestController@RequestMapping("/api/v1")@Api(value = "Employee Management System", description = "Operations pertaining to employee in Employee Management System")public class EmployeeController {     @Autowired     private EmployeeRepository employeeRepository;        @ApiOperation(value = "View a list of available employees", response = List.class)        @ApiResponses(value = {            @ApiResponse(code = 200, message = "Successfully retrieved list"),            @ApiResponse(code = 401, message = "You are not authorized to view the resource"),            @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),            @ApiResponse(code = 404, message = "The resource you were trying to reach is not found")        })     @GetMapping("/employees")     public List<Employee> getAllEmployees() {         return employeeRepository.findAll();     }     @ApiOperation(value = "Get an employee by Id")        @GetMapping("/employees/{id}")     public ResponseEntity<Employee> getEmployeeById(             @ApiParam(value = "Employee id from which employee object will retrieve", required = true) @PathVariable(value = "id") Long employeeId)             throws ResourceNotFoundException {          Employee employee = employeeRepository.findById(employeeId)            .orElseThrow(() -> new ResourceNotFoundException("Employee not found for this id :: " + employeeId));          return ResponseEntity.ok().body(employee);     }}

Answer 1

是的。您可以使用它swagger-codegen-maven-plugin来生成 REST 客户端。但在此之前，您需要在 YAML 或 JSON 中描述 REST API，主要是OpenAPI Specification 因为swagger-codegen-maven-plugin只能从本规范中编写的文件生成 REST 客户端。

其他答案假定您需要手动编写规范，而我的解决方案更进一步，可以从 REST 控制器源代码自动生成规范。

^{最新的 OpenAPI 版本是 3.0 。但是根据您导入的 swagger 注释的包，您使用的是 2.0（或之前）版本。所以我的解决方案假设您使用的是 OpenAPI 2.0。}

生成开放 API 规范

首先，您可以使用swagger-maven-plugin从 RestController 源代码生成 OpenAPI 规范。@RestController它基本上分析在指定的类中注释的 Swagger 注释<locations>，并将 OpenAPI 规范转储到/src/main/resources/swagger.json：

<plugin>

    <groupId>com.github.kongchen</groupId>

    <artifactId>swagger-maven-plugin</artifactId>

    <version>3.1.5</version>

    <configuration>

        <apiSources>

            <apiSource>

                <springmvc>true</springmvc>

                <locations>

                    <location>com.dgs.spring.springbootswagger.controller.EmployeeController</location>

                    <location>com.dgs.spring.springbootswagger.controller.FooController</location>

                </locations>

                <schemes>

                    <scheme>http</scheme>

                </schemes>

                <host>127.0.0.1:8080</host>

                <basePath>/</basePath>

                <info>

                    <title>My API</title>

                    <version>1.1.1</version>

                </info>

                <swaggerDirectory>${basedir}/src/main/resources/</swaggerDirectory>

            </apiSource>

        </apiSources>

    </configuration>

    <executions>

        <execution>

            <goals>

                <goal>generate</goal>

            </goals>

        </execution>

    </executions>

</plugin>

执行以下maven命令开始生成：

mvn clean compile

生成 Rest 客户端

生成后swagger.json，您可以将其复制并粘贴到您的客户端项目（例如/src/main/resources/swagger.json）。然后我们可以使用它swagger-codegen-maven-plugin来生成一个 HTTP 客户端。

默认情况下，它将生成整个 Maven 项目，其中包括测试用例和其他文档资料。但我想要的只是 HttpClient 的源代码，没有其他东西。经过多次尝试和错误，我确定了以下配置：

<plugin>

    <groupId>io.swagger</groupId>

    <artifactId>swagger-codegen-maven-plugin</artifactId>

    <version>2.4.7</version>

    <executions>

        <execution>

            <goals>

                <goal>generate</goal>

            </goals>

            <configuration>

                <inputSpec>${basedir}/src/main/resources/swagger.json</inputSpec>

                <language>java</language>

                <library>resttemplate</library>

                <output>${project.basedir}/target/generated-sources/</output>

                <apiPackage>com.example.demo.restclient.api</apiPackage>

                <modelPackage>com.example.demo.restclient.model</modelPackage>

                <invokerPackage>com.example.demo.restclient</invokerPackage>

                <generateApiTests>false</generateApiTests>

                <generateModelTests>false</generateModelTests>

                <generateApiDocumentation>false</generateApiDocumentation>

                <generateModelDocumentation>false</generateModelDocumentation>

                <configOptions>

                    <dateLibrary>java8</dateLibrary>

                    <sourceFolder>restclient</sourceFolder>

                </configOptions>

            </configuration>

        </execution>

    </executions>

</plugin>

生成的HTTP客户端是基于RestTemplate的，会生成到文件夹中target/generated-sources/restclient。您可能必须配置 IDE 以导入生成的客户端才能使用它。（如果是Eclipse，可以在Project Properties中配置➡️Java Build Path ➡️添加生成的rest client的文件夹）

要开始生成客户端，只需执行 maven 命令：

mvn clean compile

要使用生成的 HTTP 客户端：

ApiClient apiClient = new ApiClient();

//Override the default API base path configured in Maven

apiClient.setBasePath("http://api.example.com/api");

EmployeeManagementSystemApi api = new EmployeeManagementSystemApi(apiClient);

api.getEmployeeById(1l);

Answer 2

仅供参考，一种使用命令行的简单方法：

例如执行命令：

java -jar swagger-codegen-cli.jar generate \
  -i http://mydomain/v2/swagger.json \
  --api-package com.mypackage.api \
  --model-package com.mypackage.model \
  --invoker-package com.mypackage.invoker \
  --group-id com.mygroup \
  --artifact-id spring-swagger-codegen-api-client \
  --artifact-version 0.0.1-SNAPSHOT \
  -l java \
  --library resttemplate \
  -o spring-swagger-codegen-api-client

Swagger Codegen 支持以下客户端实现：

1. 球衣1 +杰克逊

2. Jersey2 + 杰克逊

3. 假装+杰克逊

4. OkHttp + Gson

5. Retrofit2/OkHttp + Gson

6. Spring RestTemplate + Jackson

7. Resteasy + 杰克逊

PS 如您所见，其余客户端是从 swagger 规范定义生成的，并使用“-i”参数定义。

Answer 3

招摇端点

假设您的应用程序的 Swagger 端点可以在以下位置访问：

1. 测试 Swagger 2.0 JSON API 文档

   http://localhost:8080/v2/api-docs?group=employee

   http://localhost:8080/v2/api-docs（如果你还没有设置一个名为的组employee）

2. 测试 Swagger 用户界面

   http://localhost:8080/swagger-ui.html

下载 Swagger Codegen 可执行文件

您可以从 Maven 中央存储库下载swagger-codegen-cli-2.4.7.jar 。

生成客户端代码

现在您已经有了 Swagger Codegen JAR，您可以通过执行以下命令来生成 REST 客户端：

java -jar swagger-codegen-cli-2.4.7.jar generate \
  -i http://localhost:8080/v2/api-docs?group=employee \
  -l java \
  -o swagger-codegen-client

如果没有大摇大摆的分组，

java -jar swagger-codegen-cli-2.4.7.jar generate \
  -i http://localhost:8080/v2/api-docs \
  -l java \
  -o swagger-codegen-client

选项

尽管 Swagger Codegen CLI 附带了许多选项，但我们使用的是生成客户端代码绝对必要的选项。

• -i指向您的应用程序的 URL Swagger api docs。

• -l客户端的编程语言，在这种情况下是java

• -o生成的客户端代码的输出文件夹。

执行前面生成代码的命令后，您应该注意到终端上出现以下消息：

[main] INFO io.swagger.parser.Swagger20Parser - reading from http://localhost:8080/v2/api-docs?group=employee

[main] WARN io.swagger.codegen.ignore.CodegenIgnoreProcessor - Output directory does not exist, or is inaccessible. No file (.swagger-codegen-ignore) will be evaluated.

[main] INFO io.swagger.codegen.AbstractGenerator - writing file swagger-codegen-client/src/main/java/io/swagger/client/model/Employee.java

[main] INFO io.swagger.codegen.AbstractGenerator - writing file swagger-codegen-client/docs/Employee.md

[main] INFO io.swagger.codegen.AbstractGenerator - writing file swagger-codegen-client/src/main/java/io/swagger/client/api/EmployeeControllerApi.java

...

[main] INFO io.swagger.codegen.AbstractGenerator - writing file swagger-codegen-client/src/main/java/io/swagger/client/ApiClient.java

...

REST 客户端项目

代码生成完成后，您应该注意到一个gradle/maven具有以下结构的项目：

__ swagger-codegen-client

  |__ README.md

  |__ build.gradle

  |__ build.sbt

  |__ docs

  |__ git_push.sh

  |__ gradle

  |__ gradle.properties

  |__ gradlew

  |__ gradlew.bat

  |__ pom.xml

  |__ settings.gradle

  |__ src

     |__ main

        |__ java

          |__ io.swagger.client.api

             |__ EmployeeControllerApi.java

     |__ test

        |__ java

          |__ io.swagger.client.api

             |__ EmployeeControllerApiTest.java

可以在此处找到生成的客户端项目的示例。

使用 REST 客户端

客户端项目包含很多 java 类。然而，最重要的类是EmployeeControllerApi.java。这是包含用于制作 REST 客户端类的所有逻辑的类。

另一个重要的类是EmployeeControllerApiTest.java。它向您展示了如何使用EmployeeControllerApi.java。生成的客户端项目还提供了一个非常有用的README文件。

网址更改

ApiClient类包含与建立 HTTP 客户端连接相关的信息。请确保basePath 您的 REST 应用程序正确无误。在生成的示例中，basePath有一个https://localhost:8080URL 而不是http://localhost:8080.

Java 12 的变化

生成的项目适用于 Java 8。如果您使用的是 Java 12，则必须添加以下依赖项才能使项目编译：

    <dependency>

        <groupId>javax.xml.bind</groupId>

        <artifactId>jaxb-api</artifactId>

        <version>2.3.0</version>

    </dependency>

    <dependency>

        <groupId>com.sun.xml.bind</groupId>

        <artifactId>jaxb-core</artifactId>

        <version>2.3.0</version>

    </dependency>

    <dependency>

        <groupId>com.sun.xml.bind</groupId>

        <artifactId>jaxb-impl</artifactId>

        <version>2.3.0</version>

    </dependency>

    <dependency>

        <groupId>javax.annotation</groupId>

        <artifactId>javax.annotation-api</artifactId>

        <version>1.3.2</version>

    </dependency>

示例 REST 调用

employee下面是通过调用 REST POST 方法方法来创建的示例。

Employee employee = new Employee();

employee.setId(3L);

employee.setFirstName("Sam");

employee.setLastName("Fox");

employee.setEmail("[e-mail]");

EmployeeControllerApi api = new EmployeeControllerApi();

Employee response = api.createEmployeeUsingPOST(employee);

System.out.println(response);

你应该得到类似这样的回应：

class Employee {

    email: [e-mail]

    firstName: Sam

    id: 3

    lastName: Fox

}

Answer 4

1) 转到https://editor.swagger.io创建你的 swagger 文档，我以“Swagger Petstore”为例

2) 现在选择文件，导入文件并上传下载的 swagger.json 文件

3) 打开https://swagger.io/tools/swagger-codegen/

4）使用以下步骤：

i) 将存储库克隆到磁盘 git clone https://github.com/swagger-api/swagger-codegen.git

ii) 运行 mvn clean package

iii) 将 swagger-codegen-cli.jar 文件从目标文件夹复制到计算机上的本地驱动器。

iv) 接下来执行以下命令生成客户端：

     java -jar swagger-codegen-cli.jar -i <json_file> -l python -o my_client

此命令有三个参数：

 -i Specifies the path to the input file. This can be a URL

 -l Specifies the programming language for the client

 -o Specifies the output directory where the generate code should be located

Swagger Codegen 是一个开源项目，它允许从 OpenAPI 规范自动生成 API 客户端库（SDK 生成）、服务器存根和文档。Swagger Codegen 可在 GitHub 存储库中下载，也可在集成的 SwaggerHub 平台中为任何新的或现有的 OpenAPI 定义的 API 生成。SwaggerHub 在集成的 API 设计和文档中将 Swagger 编辑器、UI 和 Codegen 工具带到云端，专为使用 Swagger (OpenAPI) 规范的 API 团队构建。

有 Maven 和 Gradle 等构建工具的插件，因为已经给出了一些答案所以这里不添加

Answer 5

只需添加一个 swagger 插件不会生成一个休息客户端，您需要按照以下步骤操作。

以 YAML 格式写下规范。根据规范结果，将生成。将规范另存为 YAML 文件。