Swagger2使用介绍

最新推荐文章于 2024-03-23 10:00:34 发布

彦登的登

最新推荐文章于 2024-03-23 10:00:34 发布

阅读量3.9k

点赞数 2

文章标签： java spring boot 开发语言

本文链接：https://blog.csdn.net/m0_59278919/article/details/127359422

版权

使用Swagger

Swagger配置项

1、构建Docket时通过select()方法配置怎么扫描接口。

SpringBoot集成Swagger

SpringBoot集成Swagger，springfox，两个jar包

● Springfox-swagger2

● swagger-springmvc

使用Swagger

1、首先 spring boot 2.6版本以上无法正常使用swagger，我这里使用的2.8.0的版本

2、要求：jdk 1.8 + 否则swagger2无法运行

3、新建一个SpringBoot-web项目

4、添加pom依赖

        <!-- swagger2 的依赖-->
        <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>

5、编写一个配置类-SwaggerConfig来配置 Swagger

package com.example.config;

import org.springframework.beans.factory.annotation.Value;
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

/**
 * Swagger2  接口测试工具
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {

    //访问地址：http://localhost:10086/swagger-ui.html
    @Value("${server.localhost.flag}")
    private String flag;

    boolean of = flag.equals("dev");

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                //方式一、二都可接入
                .apiInfo(apiInfo())
                //配置是否启用Swagger，如果是false,在浏览器将无法访问
                .enable(of)
                // 通过.select()方法，去配置扫描接口
                .select()
                //自行修改为自己项目下的controller路径，RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                //配置如何通过path过滤，我这里是获取全部
                .paths(PathSelectors.any())
                .build();
    }

    //方式一
    private ApiInfo apiInfo1() {
        return new ApiInfoBuilder()
                .title("swagger-api文档")
                .description("swagger接入教程")
                //服务条款网址
                .version("1.0")
                .build();
    }

    //方式二
    private ApiInfo apiInfo() {
        Contact contact = new Contact("王彦登", "http://localhost:10086/#/", "xxx@163.com");
        return new ApiInfo(
                "Swagger测试案例", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "https://blog.csdn.net/m0_59278919?type=collect", // 组织链接
                contact, // 联系人信息
                "Apach 2.0", // 许可
                "https://blog.csdn.net/m0_59278919?type=collect", // 许可连接
                new ArrayList<>()// 扩展
        );
    }
}

6、访问测试：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面；

Swagger配置项

1、构建Docket时通过select()方法配置怎么扫描接口。

2、根据包的路径扫描接口

除了通过包路径配置扫描接口外，还可以通过配置其他方式扫描接口，这里注释一下所有的配置方式：

//扫描所有，项目中的所有接口都会被扫描到
any() 
//不扫描接口
none() 
//通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
//通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)
//根据包路径扫描接口
basePackage(final String basePackage)

3、配置接口扫描过滤

还可以选择

//任何请求都扫描
any()
/任何请求都不扫描
none()
//通过正则表达式控制
regex(final String pathRegex) 
//通过ant()控制
ant(final String antPattern)

配置Swagger开关

1、通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                //方式一、二都可接入
                .apiInfo(apiInfo())
                //配置是否启用Swagger，如果是false,在浏览器将无法访问
                .enable(false)
                // 通过.select()方法，去配置扫描接口
                .select()
                //自行修改为自己项目下的controller路径，RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                //配置如何通过path过滤，我这里是获取全部
                .paths(PathSelectors.any())
                .build();
    }

2、动态配置当项目处于dev、sit环境时显示swagger

① 在 application.properties中配置环境信息参数

#当前环境
server.localhost.flag=dev

② 通过@Value获取参数，进行参数判断

    // http://localhost:10086/swagger-ui.html#/test-controller

    @Value("${server.localhost.flag}")
    private String flag;

    //动态配置当项目处于dev、sit环境时显示swagger
    private List<String> cases = Arrays.asList("dev","sit");
    boolean of = cases.contains(flag);

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                //方式一、二都可接入
                .apiInfo(apiInfo())
                //配置是否启用Swagger，如果是false,在浏览器将无法访问
                .enable(of)
                // 通过.select()方法，去配置扫描接口
                .select()
                //自行修改为自己项目下的controller路径，RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                //配置如何通过path过滤，我这里是获取全部
                .paths(PathSelectors.any())
                .build();
    }

实体配置（不配置也可）

1、新建一个实体类

package com.example.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
@ApiModel("用户实体")
public class Student {

    @ApiModelProperty("主键ID")
    private Integer id;

    @ApiModelProperty("用户名称")
    private String studentName;

}

2、注解定义

@ApiModel为类添加注释
@ApiModelProperty为类属性添加注释

请求的接口配置

    @RequestMapping(value = "/findAll",method = RequestMethod.GET)
    //接口的信息描述
    @ApiOperation(value="查询所有的学生信息", notes="返回的结果中有所有的结果集")
    public List<Student> findAll(){
        return studentService.findAll();
    }

常用注解

Swagger的所有注解定义在io.swagger.annotations包下

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

Swagger是个优秀的工具，现在国内已经有很多的中小型互联网公司都在使用它，相较于传统的要先出Word接口文档再测试的方式，显然这样也更符合现在的快速迭代开发行情。在正式环境要记得关闭Swagger，一来出于安全考虑二来也可以节省运行时内存。

拓展：其他皮肤

1、默认的访问 http://localhost:10086/swagger-ui.html

        <!-- 默认的访问 http://localhost:10086/swagger-ui.html-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>

2、bootstrap-ui 访问 http://localhost:8080/doc.html

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

3、mg-ui 访问 http://localhost:8080/document.html

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