Swagger使用-Spring Boot整合Swagger

1 简介

官网：swagger.io/

• Swagger 是一套功能强大且易于使用的 API 开发人员工具套件，适用于团队和个人，支持从设计和文档到测试和部署的整个 API 生命周期的开发。
• Swagger 包含开源、免费和商用工具的组合，允许任何人，从技术工程师到街头智能产品经理，构建每个人都喜欢的令人惊叹的 API。
• Swagger 由 SmartBear Software 构建，SmartBear Software 是团队软件质量工具的领导者。SmartBear 支持软件领域的一些知名人士，包括 Swagger、SoapUI 和 QAComplete。

2 Spring Boot整合Swagger

2.1 依赖和配置文件

pom.xml

<!-- web依赖 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- swagger依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- swagger-ui依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

application.properties

server.port=8800

2.2 Swagger配置类

/**
 * 开启Swagger2
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
}

测试：访问http://localhost:8800/swagger-ui.html

2.3 进阶整合配置一

2.3.1 新建Controller

/**
 * @desc: 控制器
 * @author: YanMingXin
 * @create: 2021/8/2-14:38
 **/
@RestController
public class StudentController {

    /**
     * Hello World
     *
     * @return
     */
    @RequestMapping("/hello")
    public String hello() {
        return "Hello Swagger";
    }
    
}

2.3.2 配置自定义Docket

/**
 * @desc: Swagger配置
 * @author: YanMingXin
 * @create: 2021/8/2-14:34
 **/
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 配置Docket的bean
     *
     * @return
     */
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }
       
    /**
     * 配置文档信息（apiInfo）
     *
     * @return
     */
    private ApiInfo apiInfo() {
        Contact contact = new Contact("Mr.YanMingXin", "https://blog.csdn.net/Mr_YanMingXin", "联系人邮箱/博客");
        /**
         * 参数1：标题
         * 参数2：描述
         * 参数3：版本
         * 参数4：组织链接
         * 参数5：联系人信息
         * 参数6：许可
         * 参数7：许可连接
         * 参数8：扩展
         */
        return new ApiInfo(
                "Spring Boot 整合 Swagger",
                "学习Swagger,Spring Boot 整合 Swagger",
                "v1.0",
                "https://blog.csdn.net/Mr_YanMingXin",
                contact,
                "Apache 2.0 许可",
                "https://blog.csdn.net/Mr_YanMingXin",
                new ArrayList<>()
        );
    }
}

2.3.3 测试

访问http://localhost:8800/swagger-ui.html

2.4 进阶配置二

2.4.1 配置分组

/**
 * 创建分组
 *
 * @return
 */
@Bean
public Docket docketByGroupOne() {
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
            // 配置分组
            .groupName("GroupOne");
}

/**
 * 创建分组
 *
 * @return
 */
@Bean
public Docket docketByGroupTwo() {
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
            // 配置分组
            .groupName("GroupTwo");
}

2.4.2 配置Model

Models的两种前提条件

• @ApiModel注解
• 在Controller的返回值中的返回类型

Student.java

/**
 * @desc: Student实体类
 * @author: YanMingXin
 * @create: 2021/8/2-14:34
 **/
@ApiModel("Student实体类")
public class Student {

    @ApiModelProperty("主键")
    public Integer sId;

    /**
     * private修饰会无效
     */
    @ApiModelProperty("姓名")
    private String sName;

    public Student(Integer sId, String sName) {
        this.sId = sId;
        this.sName = sName;
    }
}

StudentController.java

/**
 * @desc: 控制器
 * @author: YanMingXin
 * @create: 2021/8/2-14:38
 **/
@RestController
public class StudentController {

    /**
     * Hello World
     *
     * @return
     */
    @RequestMapping("/hello")
    public String hello() {
        return "Hello Swagger";
    }

    /**
     * 返回一个Student实体类
     *
     * @return
     */
    @RequestMapping("/student")
    public Student student() {
        return new Student(1, "zs");
    }
}

测试：

2.4.3 配置扫描包

/**
 * 根据注解扫描
 *
 * @return
 */
@Bean
public Docket docketByAnnotation() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .groupName("TestStu01")
            .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
            .apis(RequestHandlerSelectors.basePackage("org.ymx.sp_swagger.controller"))
            .build();
}

2.4.4 配置Swagger开关

配置分组的开关

@Bean
public Docket docketOnOrOff() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .groupName("Test02")
            //配置是否启用Swagger，如果是false，在浏览器将无法访问（只针对于Test02的分组）
            .enable(false)
            // 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
            .select()
            .apis(RequestHandlerSelectors.basePackage("org.ymx.sp_swagger.controller"))
            // 配置如何通过path过滤,即这里只扫描请求以/开头的接口
            .paths(PathSelectors.ant("/**"))
            .build();
}

2.5 进阶配置三

2.5.1 配置皮肤bootstrap-ui

依赖：

<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.1</version>
</dependency>

访问地址：http://localhost:8800/doc.html

2.5.2 配置皮肤Layui-ui

依赖：

<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
    <groupId>com.github.caspar-chen</groupId>
    <artifactId>swagger-ui-layer</artifactId>
    <version>1.1.3</version>
</dependency>

访问地址：http://localhost:8800/docs.html

2.5.3 配置皮肤mg-ui

依赖：

<!-- 引入swagger-ui-layer包 /document.html-->
<dependency>
    <groupId>com.zyplayer</groupId>
    <artifactId>swagger-mg-ui</artifactId>
    <version>1.0.6</version>
</dependency>

访问地址：http://localhost:8800/document.html

3 常用注解

Swagger注解	简单说明
@Api(tags = “xxx模块说明”)	作用在模块类上
@ApiOperation(“xxx接口说明”)	作用在接口方法上
@ApiModel(“xxxPOJO说明”)	作用在模型类上：如VO、BO
@ApiModelProperty(value = “xxx属性说明”,hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam(“xxx参数说明”)	作用在参数、方法和字段上，类似@ApiModelProperty