SpringBoot集成Swagger - 夜、微凉

公告

随笔档案

一、为什么使用Swagger

随着 sprnigboot、springcloud等微服务的流行，在微服务的设计下，小公司微服务小的几十，大公司大的几百上万的微服务。
这么多的微服务必定产生了大量的接口调用。而接口的调用就必定要写接口文档。
在微服务的盛行下，成千上万的接口文档编写，不可能靠人力来编写，故swagger就产生了，它采用自动化实现并解决了人力编写接口文档的问题；
它通过在接口及实体上添加几个注解的方式就能在项目启动后自动化生成接口文档，

Swagger 提供了一个全新的维护 API 文档的方式，有4大优点：
1.自动生成文档：只需要少量的注解，Swagger 就可以根据代码自动生成 API 文档，很好的保证了文档的时效性。
2.跨语言性，支持 40 多种语言。
3.Swagger UI 呈现出来的是一份可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程。
4.还可以将文档规范导入相关的工具（例如 SoapUI）, 这些工具将会为我们自动地创建自动化测试

常用注解：

@Api 注解可以用来标记 Controller 的功能

@ApiOperation 注解用来标记一个方法的作用

@ApilmplicitParam 注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入

@ApilmplicitParams 如果有多个参数，则需要使用多个 @ApilmplicitParam 注解来描述，多个 @ApilmplicitParam 注解需要放在一个 @ApilmplicitParams 注解中

@ApiModel 如果参数是一个对象，则需要在对象所在的类上加上此注解

@ApiModelProperty 如果参数是一个对象，则需要在对应的属性上加上此注解，还需要在对象所在的类上加上 @ApiModel

@ApiIgnore 注解标识此参数可以忽略

1、引入依赖

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

2、开启注解 @EnableSwagger2 和配置映射路径、要扫描的接口的未知、文档网站信息

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包路径
                .apis(RequestHandlerSelectors.basePackage("com.springboot.com.controller"))
                .paths(PathSelectors.any())
                .build();
                // return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build();
    }

    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("Spring Boot 使用 Swagger2 构建RESTful API")
                //创建人
                .contact(new Contact("Bryan", "http://blog.bianxh.top/w", ""))
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }
}

3、使用注解标注接口

@RestController
@Api(value = "企业管理",tags = "企业管理")
public class CompanyController {

    @Resource
    private IUserService userService;

    /*
        列表查询
    */
    @RequestMapping(value = "/company/list",method = RequestMethod.POST)
    @ResponseBody()
    @ApiOperation(value = "企业列表")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "companyName",required = true,value = "企业名称",paramType = "query",dataType = "String"),
            @ApiImplicitParam(name = "userName",value = "用户名称",paramType = "query",dataType = "String"),
            @ApiImplicitParam(name = "companyName",required = true,value = "企业名称",paramType = "result",dataType = "String"),
    })
    public PageInfo<CompanyModel> list(@RequestBody UserModel searchModel) {
        PageInfo<CompanyModel> list = userService.getPageList(searchModel);
        return list;
    }

}

@ApiModel(value = "企业模型")
public class CompanyModel {
    @ApiModelProperty(value = "企业编号")
    public String companyCode;
    @ApiModelProperty(value = "企业名称")
    public String companyName;
    @ApiModelProperty(value = "地址")
    public String Address;

    public String getCompanyCode() {
        return companyCode;
    }

    public void setCompanyCode(String companyCode) {
        this.companyCode = companyCode;
    }

    public String getCompanyName() {
        return companyName;
    }

    public void setCompanyName(String companyName) {
        this.companyName = companyName;
    }

    public String getAddress() {
        return Address;
    }

    public void setAddress(String address) {
        Address = address;
    }
}