如何使用Swagger代码生成简单的REST客户端？

Question

如何使用Swagger代码生成简单的REST客户端？

elv*_*vis 7 java rest-client swagger spring-boot swagger-codegen

我正在学习Swagger以及如何使用Swagger代码生成REST客户端。我知道如何使用Swagger进行文档编制，也知道如何使用Swagger生成简单的REST Server，但是我不知道如何使用Swagger代码生成简单的REST Client。

例如，我有一个简单的应用程序，它是一个REST Server，并且我想生成REST Client。我可以使用Swagger代码生成代码吗？

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);
     }

     @ApiOperation(value = "Add an employee")
     @PostMapping("/employees")
     public Employee createEmployee(
             @ApiParam(value = "Employee object store in database table", required = true) @Valid @RequestBody Employee employee) {
         return employeeRepository.save(employee);
     }

     @ApiOperation(value = "Update an employee")
     @PutMapping("/employees/{id}")
     public ResponseEntity<Employee> updateEmployee(
             @ApiParam(value = "Employee Id to update employee object", required = true) @PathVariable(value = "id") Long employeeId,
             @ApiParam(value = "Update employee object", required = true) @Valid @RequestBody Employee employeeDetails) throws ResourceNotFoundException {

          Employee employee = employeeRepository.findById(employeeId)
            .orElseThrow(() -> new ResourceNotFoundException("Employee not found for this id :: " + employeeId));

          employee.setEmail(employeeDetails.getEmail());
          employee.setLastName(employeeDetails.getLastName());
          employee.setFirstName(employeeDetails.getFirstName());
          final Employee updatedEmployee = employeeRepository.save(employee);

          return ResponseEntity.ok(updatedEmployee);
     }

     @ApiOperation(value = "Delete an employee")
     @DeleteMapping("/employees/{id}")
     public Map<String, Boolean> deleteEmployee(
             @ApiParam(value = "Employee Id from which employee object will delete from database table", required = true) @PathVariable(value = "id") Long employeeId)
       throws ResourceNotFoundException {

      Employee employee = employeeRepository.findById(employeeId)
        .orElseThrow(() -> new ResourceNotFoundException("Employee not found for this id :: " + employeeId));

      employeeRepository.delete(employee);
      Map<String, Boolean> response = new HashMap<>();
      response.put("deleted", Boolean.TRUE);

      return response;
     }
}

Run Code Online (Sandbox Code Playgroud)

之后，我开发了一个简单的REST Client：

package com.dgs.restclient.controllers;

@Controller
public class UpdateController {

    @Autowired
    private EmployeeRestClient restClient;

    @GetMapping("/showStartUpdate")
    public String showStartCheckin() {
        return "startUpdate";
    }

    @PostMapping("/startUpdate")
    public String startCheckIn(@RequestParam("employeeId") Long employeeId, ModelMap modelMap) {

        Employee employee = restClient.findEmployee(employeeId);
        modelMap.addAttribute("employee", employee);

        return "displayEmployeeDetails";
    }

    @PostMapping("/completeUpdate")
    public String completeCheckIn(@RequestParam("employeeId") Long employeeId,
            @RequestParam("employeeFirstName") String employeeFirstName,
            @RequestParam("employeeLastName") String employeeLastName,
            @RequestParam("employeeEmail") String employeeEmail) {

        EmployeeUpdateRequest employeeUpdateRequest = new EmployeeUpdateRequest();
        employeeUpdateRequest.setId(employeeId);
        employeeUpdateRequest.setFirstName(employeeFirstName);
        employeeUpdateRequest.setLastName(employeeLastName);
        employeeUpdateRequest.setEmail(employeeEmail);
        restClient.updateEmployee(employeeUpdateRequest);

        return "updateConfirmation";
    }

}

Run Code Online (Sandbox Code Playgroud)

EmployeeRestClient：

package com.dgs.restclient.integration;

@Component
public class EmployeeRestClientImpl implements EmployeeRestClient {

    private static final String EMPLOYEE_REST_URL = 
            "http://localhost:8080/api/v1/employees/";

    @Override
    public Employee findEmployee(Long id) {

        RestTemplate restTemplate = new RestTemplate();
        Employee employee = restTemplate
                .getForObject(EMPLOYEE_REST_URL + id, Employee.class);

        return employee;
    }

    @Override
    public Employee updateEmployee(EmployeeUpdateRequest request) {

        RestTemplate restTemplate = new RestTemplate();
        restTemplate
                .put(EMPLOYEE_REST_URL + request.getId(), request, Employee.class); 

        Employee employee = restTemplate
                .getForObject(EMPLOYEE_REST_URL + request.getId(), Employee.class);

        return employee;
    }

}

Run Code Online (Sandbox Code Playgroud)

该REST客户端由我开发，我想知道我是否可以使用Swagger代码生成该REST客户端，以及如何进行？我是否只需要在pom.xml中添加swagger-codegen-maven-plugin？我听说过要添加此插件和yml文件，而Swagger将创建REST Client。任何反馈将不胜感激！

Answer 1

Ari*_*era 5

更新：

您的问题在另一篇文章中得到了回答。看看：相关文章

...

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

baeldung上有一个很好的教程：如何使用swagger代码生成休息客户端

例如，执行命令：

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

Run Code Online (Sandbox Code Playgroud)

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

球衣1 +杰克逊
泽西岛2 +杰克逊
假装+杰克逊
OkHttp + Gson
Retrofit2 / OkHttp + Gson
春天RestTemplate + Jackson
Resteasy +杰克逊

PS正如您所看到的，其余客户端是根据标准规范定义生成的，并使用“ -i”参数定义。

Answer 2

Ken*_*han 5

是。您可以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>

Run Code Online (Sandbox Code Playgroud)

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

mvn clean compile

Run Code Online (Sandbox Code Playgroud)

生成Rest Client

之后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>

Run Code Online (Sandbox Code Playgroud)

生成的HTTP客户端基于RestTemplate，并将生成到该文件夹target/generated-sources/restclient。您可能必须配置IDE才能导入生成的客户端才能使用它。（对于Eclipse，可以在“项目属性”→“ Java构建路径”→“添加”中生成生成的rest客户端的文件夹中进行配置）

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

mvn clean compile

Run Code Online (Sandbox Code Playgroud)

要使用生成的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);

Run Code Online (Sandbox Code Playgroud)

注意：

如果javax/xml/bind/annotation/XmlRootElement在使用java8 +的生成过程中遇到异常，则可能需要参考this。

归档时间：	6 年，2 月前
查看次数：	2940 次
最近记录：	6 年，2 月前