SpringBoot之整合Swagger2

一、Swagger2介绍

Swagger是世界上最大的API开发工具框架，用于OpenAPI规范(OAS)，使整个API生命周期的开发，从设计和文档，到测试和部署。
Swagger从API文档中提取了手工工作，具有一系列用于生成、可视化和维护API文档的解决方案。

二、添加Swagger2依赖

我这里使用的是Gradle项目自动化构建开源工具
//swagger2
compile("io.springfox:springfox-swagger2:${swaggerVersion}")
compile("io.springfox:springfox-swagger-ui:${swaggerVersion}")


三、编写Swagger2配置类

通过@Configuration注解，让Spring-boot来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2Configuration。

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    private String basePackage = "com.qianye.controller";

    private String title = "Spring Boot 使用 Swagger2 构建RESTful API";

    private String version = "V1.0";

    private String description = "API描述";

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title(title)
                //版本号
                .version(version)
                //描述
                .description(description)
                .build();
    }
}

四、在Controller类上和方法上添加Swagger注解

@RestController
@RequestMapping(value = "/mybatis")
//用在类上，说明该类的作用
@Api(value = "控制类")
public class PersonController {

    @Resource
    private PersonService personService;

    @RequestMapping(value = "/addperson", method = RequestMethod.GET)
    public String addPerson() {
        Person person = new Person();
        person.setName("千夜");
        person.setAge(24);
        personService.addPerson(person);
        return "SUCCESS";
    }

    @RequestMapping(value = "/getpersonbyid/id/{id}", method = RequestMethod.GET)
    //用在方法上，说明方法的作用，标注在具体请求上，value和notes的作用差不多，都是对请求进行说明；tags则是对请求进行分类的
    @ApiOperation(value = "根据id获取用户")
    public Person getPersonById(@PathVariable(value = "id") Integer id) {
        return personService.getPersonById(id);
    }
}

五、其他注解

@ApiImplicitParams：用在方法上包含一组参数说明

@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

• paramType：参数放在哪个地方
• header 请求参数的获取：@RequestHeader
• query 请求参数的获取：@RequestParam
• path（用于restful接口）请求参数的获取：@PathVariable
• body（不常用）
• form（不常用）
• name：参数名
• dataType：参数类型
• required：参数是否必须传
• value：参数的意思
• defaultValue：参数的默认值

@ApiResponses：用于表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

• code：数字，例如400
• message：信息，例如”请求参数没填好”
• response：抛出异常的类