位于上海,服务全国!

位于上海,服务全国!

用Swagger进行API开发

作者:admin 分类: 时间:2019-03-01 11:55:57 点击量:2756


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变得更加容易。