Swagger是开发API最广泛使用的工具生态系统,且遵守OpenAPI规范(OAS)。Swagger(现在称为“开放式API计划”)是一种规范和框架,用于使用一种通用语言描述的REST APIs,这种语言很容易被人和机器读取和解释。JSON提供了机器可读的格式,而SwaggerUI允许用户使用浏览器查看API文档。Swagger的工具包括Swagger编辑器、Swagger codegen、Swagger UI和Swagger 检查器。还有其他一些可用的及已经广泛应用的框架,比如RAML、Summary等等,但是由于Swagger有许多突出的特性和在开发人员社区中的接受度,其的认可度最高。
图1: Swagger Petstore
在本文中,我们将使用Swagger CodeGen项目生成一个REST客户端,其在Swagger Petstore API示例的OpenAPI/Swagger spec文件中。然后,我们将创建一个Spring引导项目,在该项目中我们将使用生成的类。
Swagger整合
Swagger可以通过两种方式与REST APIs整合:
自顶向下的方法:首先是API规范,然后是代码生成。
一种自下而上的方法:首先是API代码,然后是Swagger集成。这是一个典型的场景,当已经有了一个内置的REST API并且需要集成Swagger文档时,这是非常有用的。
在这篇文章中,我们将遵循不受践踏的路径,采用自上而下的方法。
生成REST客户端
Swagger使用code-gen-cli.jar实用程序生成各种编程语言和多个框架中的REST客户端。您可以直接从swager codegen cli github知识库下载它。
要查看可用的编程语言,请输入以下命令:
java -jar swagger-codegen-cli.jar langs.
java -jar swagger-codegen-cli.jar config-help -l java
您还可以列出所有与Java相关的选项,通过输入以下内容:
Java-JavaSavig-CoDEGNE-cli.jar配置帮助-L Java
下面是生成客户端的命令:
java -jar swagger-codegen-cli.jar generate
-i http://petstore.swagger.io/v2/swagger.json
--api-package com.robgravelle.petstore.client.api
--model-package com.robgravelle.petstore.client.model
--invoker-package com.robgravelle.petstore.client.invoker
--group-id com.robgravelle
--artifact-id spring-swagger-codegen-api-client
--artifact-version 0.0.1-SNAPSHOT
-l java
--library resttemplate
-o spring-swagger-codegen-api-client
有很多命令参数,下面是每个参数的简要描述:
-i参数指定源swager文件的URL或路径。
生成类的包的名称的提供,可通过使用--api包、-model包和-invoker包标志。
--group id、--artifact id和--artifact version标志指定生成的maven项目属性。
生成客户端的编程语言由-l来实现。
执行框架得通过-library标志来实现。
现在,我们已经准备好创建一个新的Spring引导项目,该项目使用API。
首先,我们需要将生成的API客户端库的依赖项添加到项目的pom.xml文件中:
com.robgravelle
spring-swagger-codegen-api-client
0.0.1-SNAPSHOT
访问生成的类,我们需要将它们配置为bean:
@Configuration
public class PetStoreIntegrationConfig {
@Bean
public PetApi petApi() {
return new PetApi(apiClient());
}
@Bean
public ApiClient apiClient() {
return new ApiClient();
}
}
apiclient类负责配置身份验证、API的基本路径、公共头,以及执行所有API请求。下面是一些使用OAuth的代码:
@Bean
public ApiClient apiClient() {
ApiClient apiClient = new ApiClient();
OAuth petStoreAuth = (OAuth) apiClient.getAuthentication
("petstore_auth");
petStoreAuth.setAccessToken("special-key");
return apiClient;
}
接下来,我们需要导入新创建的配置,如下所示:
@SpringBootApplication
@Import(PetStoreIntegrationConfig.class)
public class PetStoreApplication {
public static void main(String[] args) throws Exception {
SpringApplication.run(PetStoreApplication.class, args);
}
}
配置API类为bean使得将它们注入到我们的Spring管理的类中变得非常简单:
@Autowired
private PetApi petApi;
public ListfindAvailablePets() {
return petApi.findPetsByStatus(Arrays.asList("available"));
}
结论
还有其它生成REST客户端的方法,例如使用Maven插件或在线生成器API。事实上,你会发现,Swagger提供了许多方法,使开发REST APIs变得更加容易。