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接口查看的功能外，还提供了调试测试功能

测试结果如下：

一、Eureka Server回顾

在前面的博客中，细心的读者可能已经发现，当我们点击某个注册到Eureka Server上的某个服务的时候，链接的界面要么报404，要么就是空的，如下图所示：

现在问题，我们已经知道了，怎么来解决了？解决思路就是整个Eureka和Swagger2，当点击链接的时候，直接跳转到Swagger2的UI界面，怎么做了？接着往下看。

二、在服务配置中添加配置

以上面注册到Eureka Server上的服务RDCLOUD-JPA为例，在该服务的配置文件中加上如下配置即可：

[java]  view plain  copy

 

1. eureka.instance.status-page-url=http://localhost:${server.port}/swagger-ui.html # ${server.port}为该服务的端口号  

同时在服务中加入Swagger2支持，不明白的可以看  spring cloud-整合Swagger2构建RESTful服务的APIs

三、再次启动服务

点击链接查看效果