Spring Boot集成Swagger

(1) 引入依赖

  在工程的pom.xml中引入以下依赖：

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.7.0</version>
</dependency>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.7.0</version>
</dependency>

(2) 配置swagger2

添加配置文件Swagger2Config

import io.swagger.annotations.ApiOperation;
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 createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //加了ApiOperation注解的类，才生成接口文档
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //包下的类，才生成接口文档
                //.apis(RequestHandlerSelectors.basePackage("site.haiyang.cms.controller"))
                .paths(PathSelectors.any())
                .build();/*
                .securitySchemes(security());*/
    }


    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot 测试使用 Swagger2 构建RESTful API")
                .contact(new Contact("Aaron", "https://blog.csdn.net/weixin_41549393", ""))
                .version("1.0")
                .description("API 描述")
                .build();
    }
}

(3) 测试

swagger2通过注解来生成API接口文档：

@Api
@RestController
@RequestMapping("api/v2/device")
public class ApiV2DeviceController{

    @Autowired
    private DeviceService deviceService;

    @ApiOperation(value = "绑定设备",notes = "绑定设备")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "phone", value = "手机号码", required = true, paramType = "query", dataType = "String"),
        @ApiImplicitParam(name = "nickName", value = "用户昵称", required = true, paramType = "query", dataType = "String")
        })
    @GetMapping("bind")
    public BaseResponse bind(参数...){
       return .....
    }

}

(4)结果截图

(5)swagger注解

1. @Api：修饰整个类，用于描述Controller类。
2. @ApiOperation：描述类的方法，或者说一个接口。
3. @ApiParam：单个参数描述。
4. @ApiModel：用对象来接收参数。
5. @ApiProperty：用对象来接收参数时，描述对象的一个字段。
6. @ApiResponse：HTTP响应的一个描述。
7. @ApiResponses：HTTP响应的整体描述。
8. @ApiIgnore：使用该注解，表示Swagger2忽略这个API。
9. @ApiError：发生错误返回的信息。
10. @ApiParamImplicit：一个请求参数。
11. @ApiParamsImplicit：多个请求参数。