springboot——集成Swagger2

一、Swagger2

日常开发过程中，我们往往需要给前端（WEB端、IOS、Android）或者第三方提供接口，如果代码与文档分开管理，很容易导致改了接口但是未修改接口文档，通过swagger2我们可以根据代码自动生成接口文档，swagger2官网描述：

When creating a REST API, good documentation is instrumental.
Moreover, every change in the API should be simultaneously described in the reference documentation. Accomplishing this manually is a tedious exercise, so automation of the process was inevitable.

二、POM.xml配置

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

	<dependency>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-devtools</artifactId>
		<scope>runtime</scope>
		<optional>true</optional>
	</dependency>
	<dependency>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-actuator</artifactId>
	</dependency>
	<dependency>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-configuration-processor</artifactId>
		<optional>true</optional>
	</dependency>
	<dependency>
		<groupId>org.projectlombok</groupId>
		<artifactId>lombok</artifactId>
		<optional>true</optional>
	</dependency>
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger2</artifactId>
		<version>2.5.0</version>
	</dependency>
	<!-- swagger-ui -->
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger-ui</artifactId>
		<version>2.5.0</version>
	</dependency>
	<dependency>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-test</artifactId>
		<scope>test</scope>
		<exclusions>
			<exclusion>
				<groupId>org.junit.vintage</groupId>
				<artifactId>junit-vintage-engine</artifactId>
			</exclusion>
		</exclusions>
	</dependency>
</dependencies>

三、启用swagger2

package com.example.swagger2;

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 docket(ApiInfo apiInfo) {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger2"))
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot 使用 Swagger2 构建RESTful API")
                .contact(new Contact("欧阳", "http://blog.bianxh.top/", ""))
                .version("1.0")
                .description("Api描述")
                .build();
    }
}

四、配置Controller

@Api("用户操作接口")
@RestController
@RequestMapping("/user")
public class UserController {

//    /**
//     * 获取用户信息
//     *
//     * @param id
//     * @return
//     */
//    @ApiOperation(value = "获取用户信息", notes = "通过用户Id获取用户信息")
//    @ApiImplicitParam(name = "id", required = true, paramType = "path", dataType = "java.lang.String")
//    @GetMapping("{id}")
//    public User getUser(@PathVariable("id") String id) {
//        User user = new User();
//        user.setId(id);
//        user.setTelephone("13568987400");
//        user.setUsername("ouyp");
//        return user;
//    }

    /**
     * 获取用户信息
     *
     * @param id
     * @param telephone
     * @return
     */
    @ApiOperation(value = "获取用户信息", tags="User", notes = "通过用户I和电话号码d获取用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", required = true, paramType = "path", dataType = "java.lang.String"),
            @ApiImplicitParam(name = "telephone", required = true, paramType = "query", dataType = "java.lang.String"),
    })
    @GetMapping("{id}")
    public User getUser(@PathVariable("id") String id, @RequestParam("telephone") String telephone) {
        User user = new User();
        user.setId(id);
        user.setTelephone(telephone);
        user.setUsername("ouyp");
        return user;
    }

    /**
     * 创建用户
     *
     * @param user
     * @return
     */
    @ApiOperation(value = "创建用户", notes = "添加新文章", tags = "User", httpMethod = "POST")
    @PostMapping("")
    public User createUser(@RequestBody User user) {
        return user;
    }

    /**
     * 更新用户
     *
     * @param id
     * @param user
     * @return
     */
    @PutMapping("{id}")
    @ApiOperation(value = "更新用户", notes = "通过Id更新用户", tags = "User", httpMethod = "PUT")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", required = true, paramType = "path", dataType = "java.lang.String")
    })
    @ApiResponse(code = 200, message = "成功", response = User.class)
    public User updateUser(@PathVariable("id") String id, @RequestBody User user) {
        user.setId(id);
        return user;
    }
}

启动Spring boot，然后访问：http://127.0.0.1:8080/swagger-ui.html即可看到如下结果：

点击show/Hide打开后的效果：

五、SwaggerAPI详细配置

====================Spring Boot实战：集成Swagger2 =================
5.1 @ApiOperation，整个接口属性配置：
   value：接口说明，展示在接口列表。
   notes：接口详细说明，展示在接口的详情页。
   tags：接口的标签，相同标签的接口会在一个标签页下展示。
   httpMethod：支持的HTTP的方法。

5.2 @ApiImplicitParams，@ApiImplicitParam的容器，可包含多个@ApiImplicitParam注解

5.3 @ApiImplicitParam，请求参数属性配置：
name：参数名称
value：参数说明
required：是否必须
dataType：数据类型：path，query，body，header，form
5.4 @ApiResponses，@ApiResponse容器，可以包含多个@ApiResponse注解

5.5 @ApiResponse，返回结果属性配置：
code：返回结果的编码。
message：返回结果的说明。
response：返回结果对应的类

5.6 @ApiModel是对整个类的属性的配置：
value：类的说明
description：详细描述

5.7 @ApiModelProperty是对具体每个字段的属性配置：
name：字段名称
value：字段的说明
required：是否必须
example：示例值
hidden：是否显示

使用示例：

@ApiModel("用户信息")
@Data
public class User implements Serializable {
    @ApiModelProperty("主键")
    private String id;
    @ApiModelProperty("用户姓名")
    private String username;
    @ApiModelProperty("联系电话")
    private String telephone;
}

====================Spring Boot实战：集成Swagger2 =================

六、参考链接

1. Springboot集成Swagger操作步骤
2. Spring Boot实战：集成Swagger2