SpringBoot基础教程(四)——与Swagger2的结合
我们在实际开发过程中经常会遇到一个问题，就是接口文档。有时候接口还没开发完但是接口文档需要先给出，因为其他方也可以根据接口文档先搞起来。但是有时候在开发过程中会发现当初定义的不是那么完善，就会更改。这个过程又涉及到一些沟通之类的比较繁琐的事情。有问题出现，就会有有心人出来帮忙解决。一个产品Swagger2应运而生。他可以在我们定义Controller时通过Swagger2注解的方式自动生成文档，只要服务起着，这个文档就能一直看到。当接口发生调整时，接口文档也能跟着调整，是一款非常好用的工具。
废话不多说，我们继续看pom
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
</dependency>
springfox-swagger2是swagger2的核心库，包括了一些注解及处理逻辑等。springfox-swagger-ui 是页面的展示。下面我们看看配置文件
package com.shuqi;
import io.swagger.annotations.Api;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket apiDocket() {
ApiInfo apiInfo = new ApiInfoBuilder().title("title").description("description")
.termsOfServiceUrl("").version("1.0")
.contact(new Contact("name", "", "email")).build();
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo).select()
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class)).paths(PathSelectors.any())
.build();
}
}
@EnableSwagger2表示激活此功能，实现是通过导入进来了Swagger2DocumentationConfiguration这个配置类@Import({Swagger2DocumentationConfiguration.class})
既然是个配置文件，Bean就少不了。ApiInfo是关于Api文件的基础描述，比如说标题，描述，版本号，联系人等基础信息。其中我想说的是
apis(RequestHandlerSelectors.withClassAnnotation(Api.class))他可以定制要展示的Controller中的文档，比如这里我定义的是类上加了Api这个注解，那么那些没有加这个注解的Controller就不会展示到页面上，所以留给我们的操作空间还是蛮大的。看一眼Controller是怎么定义的
package com.shuqi.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@RestController
@Api
public class HelloController {
@RequestMapping(value = "/hello",method = RequestMethod.GET)
@ApiOperation(value = "hello", notes = "hello")
public String hello(@ApiParam("姓名") @RequestParam String name,@ApiParam("年龄") @RequestParam Integer age) {
return "我的名字叫" + name + ",年龄是" + age;
}
}
可以看到我们再类上加了Api的注解。在方法上加了ApiOperation的注解，标示是一个Api 接口，ApiParam标示对接口参数的描述。
下面我们启动项目，看一下效果。启动后，输入http://localhost:8080/swagger-ui.html，看到下面的页面
image.png
他不仅可以作为接口文档，还可以测试功能
image.png
输入值后点击Try it out
image.png
使用起来相当方便，搞起来吧。
下节将的内容是：SpringBoot基础教程(五)——与本地缓存的结合
