Spring Boot中结合Swagger2构建接口

一、简介

Swagger是全球最大的开源API规范（OAS）API开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发。本篇只介绍如何在Spring boot项目中使用Swagger2，自动为API生成注释和规范API。

二、教程

1 创建maven项目，引进依赖

<!---------spring boot依赖----------->
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.5.2.RELEASE</version>
<relativePath/>
</parent>

<dependencies>

<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-logging</artifactId>
</dependency>

<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>

<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-tomcat</artifactId>
</dependency>

<!----------swagge依赖----------->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>

<!----------lombok插件依赖----------->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>1.16.10</version>
</dependency>
</dependencies>

2 wagger2配置

@Configuration //spring boot配置注解
@EnableSwagger2 //启用swagger2功能注解
public class Swagger2Config {
@Bean
public Docket createRestfulApi() {//api文档实例
return new Docket(DocumentationType.SWAGGER_2)//文档类型：DocumentationType.SWAGGER_2
.apiInfo(apiInfo())//api信息
.select()//构建api选择器
.apis(RequestHandlerSelectors.basePackage("com.yyh.controller"))//api选择器选择api的包
.paths(PathSelectors.any())//api选择器选择包路径下任何api显示在文档中
.build();//创建文档
}

private ApiInfo apiInfo() {//接口的相关信息
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful接口")
.description("接口描述")
.termsOfServiceUrl("termsOfServiceUrl")
.contact("new Contact")
.version("1.0")
.license("http://springfox.github.io/springfox/docs/current/")
.licenseUrl("http://springfox.github.io/springfox/docs/current/")
.build();
}

}

3 api相关注解的使用

@RestController//接口注解
@Api(value="用户接口",tags={"dogAPi"})//接口简要标注，对中文的支持不太好
@RequestMapping(value = "/swagger")//接口基本路径
public class AnimalController {
//接口需要的参数，可以有多个，这里只写了一个，它的paramType还有path、query、body、form几种，
@ApiImplicitParams({
@ApiImplicitParam(paramType = "header", name = "Token", value = "token", dataType = "String", required = true,defaultValue = "123")})
//接口功能描述
@ApiOperation(value = "获取一只狗")
//接口响应信息，这里定义了一个401，当出现401，接口返回的是自定的错误AnimalError的实例。当然可以定义多个。
@ApiResponses(value = { @ApiResponse(code = 401, message = "请求未通过认证.", response = AnimalError.class) })
@RequestMapping(value="/onedog", method = RequestMethod.GET)
public Dog oneDog(){
return new Dog();
}

@ApiImplicitParams({
@ApiImplicitParam(paramType = "header", name = "Token", value = "token", dataType = "String", required = true,defaultValue = "123")})
@ApiOperation(value = "创建一只狗")
@ApiResponses(value = { @ApiResponse(code = 401, message = "请求未通过认证.", response = AnimalError.class) })
@RequestMapping(value="/dog/{name}", method = RequestMethod.GET)
public Dog createDog(
@ApiParam(defaultValue = "二哈")//@ApiParam和@RequestParam注解作用效果相同
@PathVariable("name") String name){
Dog dog = new Dog();
dog.setName(name);
return dog;
}

4 查看效果

4.1 浏览器输入网址http://localhost:8080/swagger-ui.html#/



4.2 展开接口列表



4.3 下面我们进入第一个接口中



4.5 调用成功后

三、后续

此处只介绍了Spring boot中如何简单的使用swagger，详细学习还得看官方文档：http://springfox.github.io/springfox/docs/current/

源码：https://github.com/NapWells/java_framework_learn/tree/master/springswagger