Spring Boot 整合 Swagger2

在前后端分离的项目当中，API文档是不可或缺的，Swagger 是一个可以根据我们代码中的注解元信息自动生成在线API文档的工具。

在前后端分离的项目当中，API 文档是不可或缺的，Swagger 是一个可以根据我们代码中的注解元信息自动生成在线 API 文档的工具。这篇文章介绍一下 Swagger 的用法以及 Spring Boot 如何集成 Swagger。

Swagger 常用注解

• @Api：修饰整个类，描述Controller的作用
• @ApiOperation：描述一个类的一个方法，或者说一个接口
• @ApiParam：请求的单个参数描述
• @ApiModel：用对象来接收请求参数
• @ApiProperty：用对象接收参数时，描述对象的一个字段
• @ApiResponse：HTTP响应其中1个描述
• @ApiResponses：HTTP响应整体描述
• @ApiIgnore：使用该注解忽略这个API
• @ApiError ：发生错误返回的信息
• @ApiImplicitParam：一个请求参数
• @ApiImplicitParams：多个请求参数

Spring Boot 集成 Swagger

引入 Swagger 依赖

        <!-- swagger       -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger-version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger-version}</version>
        </dependency>
        <!--   更加友好的UI界面依赖     -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>
	<!--统一依赖版本控制-->
    <properties>
        <swagger-version>2.9.2</swagger-version>
    </properties>

编写配置类

这边编写了两个分组：web端API接口和移动端API接口文档

@Configuration
@EnableSwagger2
public class Swagger2Config {

    /**
     * 创建官网后台接口文档
     */
    @Bean
    public Docket webApi() {
        ParameterBuilder header = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        header.name("Authorization").description("登陆token")
                .modelRef(new ModelRef("string")).parameterType("header")
                .required(false).defaultValue("Bearer ");
        pars.add(header.build());
        //使用链式调用
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(webApiInfo())
                .globalOperationParameters(pars)
                .groupName("webApi")
                .select()
                //扫描基础包
                .apis(RequestHandlerSelectors.basePackage("com.example.record.rest.web"))
                .paths(PathSelectors.ant("/api/**"))
                .build();
    }

    /**
     * api信息
     */
    private ApiInfo webApiInfo() {
        return new ApiInfoBuilder()
                .title("官网后台接口")
                .description("官网后台接口")
                .termsOfServiceUrl("https://www.kangpeiqin.cn/#/index")
                .version("1.0")
                .build();
    }

    /**
     * 移动端接口文档
     */
    @Bean("mb")
    public Docket mobile() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(mobileInfo())
                .groupName("mobile")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.record.rest.mobile"))
                .paths(PathSelectors.ant("/mb/**"))
                .build();
    }

    private ApiInfo mobileInfo() {
        return new ApiInfoBuilder()
                .title("移动端接口")
                .description("移动端接口")
                .termsOfServiceUrl("https://www.kangpeiqin.cn/#/index")
                .version("1.0")
                .build();
    }

}

访问我们的接口文档地址：