spring cloud-整合Swagger2构建RESTful服务的APIs

前言

在前面的博客中，我们将服务注册到了Eureka上，可以从Eureka的UI界面中，看到有哪些服务已经注册到了Eureka Server上，但是，如果我们想查看当前服务提供了哪些RESTful接口方法的话，就无从获取了，传统的方法是梳理一篇服务的接口文档来供开发人员之间来进行交流，这种情况下，很多时候，会造成文档和代码的不一致性，比如说代码改了，但是接口文档没有改等问题，而Swagger2则给我们提供了一套完美的解决方案，下面，我们来看看Swagger2是如何来解决问题的。

一、引入Swagger2依赖的jar包

[html]  view plain  copy

1. <!-- swagger2 -->  
2.         <dependency>  
3.             <groupId>io.springfox</groupId>  
4.             <artifactId>springfox-swagger2</artifactId>  
5.             <version>2.2.2</version>  
6.         </dependency>  
7.         <dependency>  
8.             <groupId>io.springfox</groupId>  
9.             <artifactId>springfox-swagger-ui</artifactId>  
10.             <version>2.2.2</version>  
11.         </dependency>  

二、初始化Swagger2的配置

[java]  view plain  copy

1. @Configuration  
2. @EnableSwagger2 // 启用Swagger2  
3. public class Swagger2 {  
4.   
5.     @Bean  
6.     public Docket createRestApi() {// 创建API基本信息  
7.         return new Docket(DocumentationType.SWAGGER_2)  
8.                 .apiInfo(apiInfo())  
9.                 .select()  
10.                 .apis(RequestHandlerSelectors.basePackage("com.chhliu.jpa"))// 扫描该包下的所有需要在Swagger中展示的API，@ApiIgnore注解标注的除外  
11.                 .paths(PathSelectors.any())  
12.                 .build();  
13.     }  
14.   
15.     private ApiInfo apiInfo() {// 创建API的基本信息，这些信息会在Swagger UI中进行显示  
16.         return new ApiInfoBuilder()  
17.                 .title("Spring Boot中使用Swagger2构建RESTful APIs")// API 标题  
18.                 .description("rdcloud-jpa提供的RESTful APIs")// API描述  
19.                 .contact("chhliu@")// 联系人  
20.                 .version("1.0")// 版本号  
21.                 .build();  
22.     }  
23.   
24. }  

注：该配置类需要在Application同级目录下创建，在项目启动的时候，就初始化该配置类

三、完善API文档信息

[java]  view plain  copy

1. public interface SonarControllerI {  
2.     @ApiOperation(value="获取项目组Sonar对应的Url信息", notes="根据id获取项目组Sonar对应的Url信息")// 使用该注解描述接口方法信息  
3.     @ApiImplicitParams({  
4.             @ApiImplicitParam(name = "id", value = "SonarUrl表ID", required = true, dataType = "Long", paramType="path")  
5.     })// 使用该注解描述方法参数信息，此处需要注意的是paramType参数，需要配置成path，否则在UI中访问接口方法时，会报错  
6.     @GetMapping("/get/{id}")  
7.     SonarUrl get(@PathVariable Long id);  
8.       
9.     @ApiOperation(value="获取项目组Sonar对应的所有Url信息")  
10.     @GetMapping("/get/all")  
11.     List<SonarUrl> getAll();  
12. }  

注：paramType表示参数的类型，可选的值为"path","body","query","header","form"

四、完善返回类型信息

[java]  view plain  copy

1. @Entity(name = "SONAR_URL")  
2. public class SonarUrl implements Serializable {  
3.   
4.     /** 
5.      *  
6.      */  
7.     private static final long serialVersionUID = 1L;  
8.     @ApiModelProperty(value="主键", hidden=false, notes="主键，隐藏", required=true, dataType="Long")// 使用该注解描述属性信息,当hidden=true时，该属性不会在api中显示  
9.     @Id  
10.     @GeneratedValue(strategy = GenerationType.AUTO)  
11.     private Long id;  
12.       
13.     @ApiModelProperty(value="URL链接地址")  
14.     @Column(name="URL")  
15.     private String url;  
16.       
17.     @ApiModelProperty(value="项目组")  
18.     @Column(name="TEAM")  
19.     private String team;  
20.   
21.     @ApiModelProperty(value="部门")  
22.     @Column(name="DEPARTMENT")  
23.     private String department;  
24.         ……省略getter，setter方法……  
25.  }  

五、启动应用

1、在浏览器中输入：http://localhost:7622/swagger-ui.html

2、结果如下：

六、API文档访问与测试

Swagger除了提供API接口查看的功能外，还提供了调试测试功能

测试结果如下：