Spring Boot中使用Swagger CodeGen生成REST client

阚原

2023-12-01

Swagger是一个非常好用的API工具，我们会使用Swagger来暴露API给外界测试，那么有没有简单的办法来生成对应的调client呢？

Swagger CodeGen是一个REST 客户端生成工具，它可以从Open API的规范定义文件中生成对应的REST Client代码。本文我们将会举例说明如何通过OpenAPI 规范定义文件自动生成REST Client。

什么是Open API规范定义文件呢？

OpenAPI规范（OAS）为RESTful API定义了一个与语言无关的标准接口，使人类和计算机都可以发现和理解服务的功能，而无需访问源代码，文档或通过网络流量检查。正确定义后，使用者可以使用最少的实现逻辑来理解远程服务并与之交互。

然后，文档生成工具可以使用OpenAPI定义来显示API，代码生成工具可以使用各种编程语言，测试工具和许多其他用例来生成服务器和客户端。

值得一提的是OpenAPI规范最早也是Swagger提出来的，后面被捐赠给了社区。

推荐的OpenAPI 文档名字通常为openapi.json 或者 openapi.yaml。

我们看一个swagger自带的 petstore open api 例子： https://petstore.swagger.io/v2/swagger.json

 {
  "swagger": "2.0",
  "info": {
    "description": "This is a sample server Petstore server.  You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).  For this sample, you can use the api key `special-key` to test the authorization filters.",
    "version": "1.0.3",
    "title": "Swagger Petstore",
    "termsOfService": "http://swagger.io/terms/",
    "contact": {
      "email": "apiteam@swagger.io"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    }
  },
  "host": "petstore.swagger.io",
  "basePath": "/v2",
  "tags": [
     ...
  ],
  "schemes": [
    "https",
    "http"
  ],
  "paths": {
    ...
       
  "definitions": {
     ...
     
  },
  "externalDocs": {
    "description": "Find out more about Swagger",
    "url": "http://swagger.io"
  }
}

我们可以看到在这个open API 定义文件里面包含了我们在swagger界面上看到的一切，paths，definitions等。

生成Rest Client

有了Open Api定义文件之后，我们就可以使用 swagger-codegen-cli 来生成对应的rest client文件了。

目前为止，最新的swagger-codegen-cli版本是2.4.12，我们可以从这里下载 https://search.maven.org/classic/remotecontent?filepath=io/swagger/swagger-codegen-cli/2.4.12/swagger-codegen-cli-2.4.12.jar。

下载到本地之后，我们可以通过如下命令来生成rest client：

java -jar swagger-codegen-cli-2.4.12.jar generate \
  -i http://petstore.swagger.io/v2/swagger.json \
  --api-package com.flydean.client.api \
  --model-package com.flydean.client.model \
  --invoker-package com.flydean.client.invoker \
  --group-id com.flydean \
  --artifact-id springboot-generate-restclient \
  --artifact-version 0.0.1-SNAPSHOT \
  -l java \
  --library resttemplate \
  -o springboot-generate-restclient

上述的参数包含：

-i 指定了open api 定义文件的地址
–api-package, –model-package, –invoker-package 指定了生成文件的package
–group-id, –artifact-id, –artifact-version 指定生成的maven 项目的属性
-l 指明生成的代码编程语言
–library 指定了实际的实现框架
-o 指定输出文件目录

Swagger Codegen 支持如下的Java 库：

jersey1 – Jersey1 + Jackson
jersey2 – Jersey2 + Jackson
feign – OpenFeign + Jackson
okhttp-gson – OkHttp + Gson
retrofit (Obsolete) – Retrofit1/OkHttp + Gson
retrofit2 – Retrofit2/OkHttp + Gson
rest-template – Spring RestTemplate + Jackson
rest-easy – Resteasy + Jackson

在Spring Boot中使用

我们把生成的代码拷贝到我们的Spring Boot项目中。然后通过下面的代码来启动应用程序:

@SpringBootApplication
public class GenerateClientApp {

    public static void main(String[] args) {
        SpringApplication.run(GenerateClientApp.class, args);
    }


    @Bean
    public RestTemplate restTemplate(RestTemplateBuilder builder) {
        return builder.build();
    }

}

我们再定义一个controller：

@RestController
public class PetController {

    @Autowired
    private PetApi petApi;

    @GetMapping("/api/findAvailablePets")
    public List<Pet> findAvailablePets() {
        return petApi.findPetsByStatus(Arrays.asList("available"));
    }
}

现在通过curl localhost:8080/api/findAvailablePets就可以远程调用http://petstore.swagger.io/v2/swagger.json 里面暴露的接口了。

API Client 配置

默认情况下ApiClient是默认的不需要认证的，如果需要认证，可以自定义ApiClient如下：

@Bean
public ApiClient apiClient() {
    ApiClient apiClient = new ApiClient();
 
    OAuth petStoreAuth = (OAuth) apiClient.getAuthentication("petstore_auth");
    petStoreAuth.setAccessToken("special-key");
 
    return apiClient;
}

使用Maven plugin

除了使用cli命令之外，我们还可以在pom中添加plugin来实现这个功能：

<build>
    <plugins>
    <plugin>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-codegen-maven-plugin</artifactId>
        <version>2.4.12</version>
        <executions>
            <execution>
                <goals>
                    <goal>generate</goal>
                </goals>
                <configuration>
                    <inputSpec>swagger.json</inputSpec>
                    <language>java</language>
                    <library>resttemplate</library>
                </configuration>
            </execution>
        </executions>
    </plugin>
    </plugins>
    </build>

在线生成API

我们可以通过http://generator.swagger.io来在线生成API代码：

curl -X POST -H "content-type:application/json" \
-d '{"swaggerUrl":"http://petstore.swagger.io/v2/swagger.json"}' \
http://generator.swagger.io/api/gen/clients/java

该命令会返回一个包含代码的zip包供你下载。

本文的例子可以参考 https://github.com/ddean2009/learn-springboot2/tree/master/springboot-generate-restclient

更多精彩内容且看：

更多教程请参考 flydean的博客

Spring Boot中使用Swagger CodeGen生成REST client

什么是Open API规范定义文件呢？

生成Rest Client

在Spring Boot中使用

API Client 配置

使用Maven plugin

在线生成API

相关阅读

相关文章

相关问答

相关文档