SpringBoot 整合Swagger API文档

1. Maven依赖

<!-- Swagger2 JSON API文档 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
    <exclusions>
        <exclusion>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<!-- 修复Swagger转换错误问题 -->
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-models</artifactId>
    <version>1.5.21</version>
    <scope>compile</scope>
</dependency>
<!-- Swagger Bootstrap用户界面 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

2. Swagger注解

　　A. @EnableSwagger2：开启Swagger API文档；

　　B. @Api：修饰整个类，描述Controller的作用；

　　C. @ApiOperation：描述类的一个方法；

　　D. @ApiImplicitParams：描述方法的多个参数；

　　E. @ApiImplicitParam：描述方法的一个参数；

　　　　name：参数名；

　　　　value：参数描述；

　　　　dataType：参数的数据类型，Long/String；

　　　　required：参数是否必填，true/false；

　　　　paramType：请求类型，path—以地址的形式提交数据、query—直接跟参数完成自动映射赋值、body—以流的形式提交，仅支持POST、header—以参数在请求头里提交、form—以form表单的形式提交，仅支持POST；

　　　　defaultValue：默认值；

　　F. @ApiModel：用对象来接收参数；

　　G. @ApiModelProperty：用对象接收参数时，描述对象的一个字段；

3. Swagger配置类

package com.ruhuanxingyun.minio.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.RequestHandler;
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;

import java.util.function.Predicate;

/**
 * @description: Swagger文档 配置类
 * @author: ruphie
 * @date: Create in 2020/12/19 13:49
 * @company: ruhuanxingyun
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 前端接口API
     *
     * @param environment 环境变量
     * @return docket
     */
    @Bean
    public Docket clientDocket(Environment environment) {
        // 开发和测试环境开启Swagger
        boolean enable = environment.acceptsProfiles(Profiles.of("dev", "test"));
        // 配置需要扫描的包
        Predicate<RequestHandler> apis = RequestHandlerSelectors.basePackage("com.ruhuanxingyun.minio.controller")::apply;

        return new Docket(DocumentationType.SWAGGER_2)
                .enable(enable)
                .apiInfo(this.apiInfo())
                .groupName("前端对接API")
                .select()
                .apis(apis::test)
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 后端接口API
     *
     * @param environment 环境变量
     * @return docket
     */
    /*@Bean
    public Docket serverDocket(Environment environment) {
        // 开发和测试环境开启Swagger
        boolean enable = environment.acceptsProfiles(Profiles.of("dev"));
        // 配置需要扫描的包
        Predicate<RequestHandler> apis = RequestHandlerSelectors.basePackage("com.ruhuanxingyun.minio.controller")::apply;

        return new Docket(DocumentationType.SWAGGER_2)
                .enable(enable)
                .apiInfo(this.apiInfo())
                .groupName("服务端对接API")
                .select()
                .apis(apis::test)
                .paths(PathSelectors.any())
                .build();
    }*/

    /**
     * 文档描述
     *
     * @return 描述信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("文件服务接口API")
                .description("Minio存储API文档")
                .version("1.0.0")
                .termsOfServiceUrl("http://localhost:8083")
                .build();
    }

}

4. 访问地址

　　A. swagger原生界面访问地址：http://localhost:8080/swagger-ui.html；

　　B. swagger Bootstrap界面访问地址：http://localhost:8080/doc.html,，提供文档说明和在线调试两大功能；

 

 

可参考：Knife4j API文档