SpringBoot集成Swagger2

SpringBoot集成Swagger2

第一步：在pom文件中引入下面的依赖：

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

第二步：创建Swagger2的配置类

package com.example.demo.config;

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2Configuration {

    @Bean
    public Docket buildDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(buildApiInfo())
                .select()
                //此处的包路径需要修改为自己的
                .apis(RequestHandlerSelectors.basePackage("com.example"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo buildApiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger API在线文档")
                .description("SpringBoot Swagger2")
                .build();
    }
}

以上两步完成后，启动SpringBoot应用，在浏览器的url中加入swagger-ui.html，如(http://localhost:8090/swagger-ui.html)即可进入Swagger2的页面，如下图

image.png

在开发中常用的Swagger2注解

@Api注解：放在controller层的类上面
主要属性有tag、value

@Api(tags = "工单申请相关接口", value = "ApplicationFormController")
@Slf4j
@RestController
@RequestMapping(value = "/applicationFormController")
public class ApplicationFormController extends BaseController<ApplicationForm, String> {
}

@ApiOperation注解：放在controller内部的方法上面
主要属性有value、notes
@ApiImplicitParams注解：
@ApiImplicitParam注解：

     /**
     * 查询所有，带分页
     *
     * @return 返回查询到的所有结果集
     */
    @ApiOperation(value = "findAll", notes = "查询所有，带分页")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "pageIndex", value = "当前页码", dataType = "int", paramType = "query"),
            @ApiImplicitParam(name = "pageSize", value = "每页数量", dataType = "int", paramType = "query"),
            @ApiImplicitParam(name = "direction", value = "排序规则(desc/asc)", dataType = "String", paramType = "query"),
            @ApiImplicitParam(name = "properties", value = "排序属性", dataType = "String", paramType = "query")
    })
    @PostMapping(value = "/findAll")
    public JsonResult findAll(@RequestParam(required = false, defaultValue = "1") int pageIndex,//当前页码
                              @RequestParam(required = false, defaultValue = "10") int pageSize,//每页数量
                              @RequestParam(required = false) String direction,//排序规则(asc/desc)
                              @RequestParam(required = false) String properties//排序属性
    ) {
        return JsonResult.success(applicationFormService.findAll(pageIndex, pageSize, direction, properties));
    }

总结

Swagger中常用的注解

API	作用
@Api	用在Controller类上面
@ApiOperation	用在Controller类的方法上面
@ApiImplicitParams	用在Controller类的方法上面（当方法有多个参数时）
@ApiImplicitParam	用在@ApiImplicitParams注解内
@ApiModel	用在POJO实体类上面
@ApiModelProperty	用在POJO实体类的属性上面