springboot整合Swagger2

Swagger2是一个开源项目，用于为RESTful Web服务自动生成REST API文档。 它提供了一个用户界面，可通过浏览器访问访问和调试API接口。

1、配置maven依赖

<!-- swagger2 配置 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.4.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.4.0</version>
</dependency>

在github上有扩展的swagger-ui插件，地址：https://github.com/xiaoymin/swagger-bootstrap-ui，如果想使用这个依赖，可以加入以下依赖即可

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.6</version>
</dependency>

对于使用Gradle构建的项目，在build.gradle 中加入

compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.4.0'
compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.4.0'

2、在Spring Boot应用程序中配置Swagger2

创建swagger2的配置启动类，配置swagger2核心配置 docket和ApiInfo两个bean

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 Swagger2 {
    // 
    @Bean
    public Docket createRestApi() {
        //指定api类型为swagger2
        return new Docket(DocumentationType.SWAGGER_2) 
                    //配置项目api文档的描述
                    .apiInfo(apiInfo()) 
                    .select()
                    //需要生产api文档的包路径
                    .apis(RequestHandlerSelectors.basePackage("xx.controller"))
                    .paths(PathSelectors.any())         // 所有controller
                    .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //文档页标题
                .title("文档页标题")
                //联系人信息
                .contact(new Contact("领悟书生","https://www.656463.com"))
                .description("详细信息")
                // 文档版本号
                .version("1.0.1")
                // 网站地址
                .termsOfServiceUrl("https://www.656463.com")
                .build();
    }
}

3、配置Swagger2 api

3.1、配置整个的API描述

@Api(value = "用户操作", tags = {"操作用户的相关接口"})

3.2、忽略某个接口类

@ApiIgnore

3.3、接口api配置

使用@ApiOperation配置接口配置

使用@ApiParam配置参数描述

@ApiOperation(value = "根据用户Id获取用户信息", notes = "根据用户Id获取用户信息", httpMethod = "GET")
@PostMapping("getUser")
public void getUser(
        @ApiParam(name = "userId", value = "用户id", required = true)
        @RequestParam String userId) {
           ...... 
        }
}

如果参数是复杂对象，使用@ApiModel注释对象，@ApiModelProperty注释属性，如

@ApiModel(value = "用户对象", description = "用户对象")
public class User {
    @ApiModelProperty(value = "用户名", name = "username", example = "张三", required = true)
    private String username;
    @ApiModelProperty(value = "密码", name = "password", example = "123456", required = true)
    private String password;
    
    //set get 
}