Swagger简介

问题的引入:前后端分离已成为互联网项目开发最流行的使用方式。但是也出现一个问题,即前后端集成联调,前端人员和后端人员无法做到“及时协商,尽早解决”。

解决: Swagger应运而生。

Swagger

  • 号称世界上最流行的Api框架
  • RestFul Api文档在线自动生成工具,Api文档与Api定义同步更新
  • 直接运行,可以在线测试Api接口
  • 支持多种语言

Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。

swagger官网

如何使用Swagger

在项目中使用Swagger需要springfox

相关的两个依赖:

  • springfox-swagger2
  • springfox-swagger-ui

要求:jdk 1.8 + 否则swagger2无法运行

springfox:是一个开源的API Doc的框架, 它的前身是swagger-springmvc,可以将我们的Controller中的方法以文档的形式展现。

SpringFox能做什么?

  1. 首先、使前端和后端更加解耦,前后端的对接通常是API形式,而后端开发人员在开发的过程中,提供的API和描述文档却是难以同步的,往往是开发代码完成了,但文档描述并不及时,甚至会忘记这一环节,导致前端调用API时经常发生错误,因此,springfox应运而生,它将前后端有效分离,并保证了API与文档的实时同步;
  2. 其次、使用springfox生成的接口文档直观可视,也帮助后端开发人员脱离了写接口文档的痛苦,及避免不厌其烦的解说各个接口需要的参数和返回结果;
  3. 再次、springfox支持在线测试,可实时检查参数和返回值。

SpringBoot集成Swagger

1.新建一个SpringBoot-web项目

2.导入相关依赖

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

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

3.编写一个相关配置类,类上加上注解@Configuration和@EnableSwagger2

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

}

此时,Swagger就可以实现最基本的使用了。访问http://localhost:8080/swagger-ui.html 即可查看Swagger的基本页面。


4. 配置Swagger

Swagger的具体配置

配置Swagger的bean实例Docket

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());//此方法定义Swagger页面的基本信息,不配置则有默认的信息
    }

自定义Swagger页面的基本信息

    protected ApiInfo apiInfo(){
        //配置作者信息
        Contact contact=new Contact("志千","http://zhiqian.site","1270768450");
        return new ApiInfo(
                "志千的SwaggerAPI文档",
                "开始",
                "v1.0",
                "http://zhiqian.site",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>()
        );
    }

此时Swagger页面就变成了

Swagger配置扫描接口

在定义Swagger的bean实例Docket时就可以设置扫描条件了。

    //配置Swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//此方法定义Swagger页面的基本信息,不配置则有默认的信息
                .select()
                //RequestHandlerSelectors配置要扫描接口的方式
                .apis(RequestHandlerSelectors.basePackage("com.zhiqian.swagger.controller"))
                //paths() 过滤什么路径,就是路径必须满足条件
                .paths(PathSelectors.ant("/zhiqian/**"))
                .build();
    }

使用链式编程在后面追加select().apis()即可设置扫描接口规则,其中参数为RequestHandlerSelectors,它有很多方法:
1.basePackage():指定要扫描的包(最常用)
2.any() 扫描全部
3.none() 不扫描
4.withClassAnnotation(xxx.class) :扫描类上的注解,需要传入注解的class
5.withMethodAnnotation(xxx.class) 扫描方法上的注解,需要传入注解的class

paths(""):过滤路径,路径必须满足参数中配置的路径条件才能被扫描

注意:

  • apis()和paths()必须追加在select()与build()之间。
  • 链式编程后面还可以追加enable()方法来设置是否开启Swagger,默认为true,false表示关闭

配置Api文档的分组

给组命名的方法:

groupName("组名")

该方法追加到.apiInfo()方法的后面即可。
一般我们一个组对应一个Docket的实例。

实体类配置

只要我们的接口中的返回值存在实体类,它就会被扫描到Swagger中

    @PostMapping("/user")
    public User user(){
        return new User();
    }

此时Swagger页面就就存在该实体类了

我们还可以在实体类上加上@ApiModel注解,在属性上加上@ApiModelProperty注解。
这两个注解的作用是给Swagger页面上对应的实体类加上注释。

Swagger页面效果:

补充

  • 我们也可以给Controller类中的方法加上@ApiOperation()注解,给该方法在Swagger页面上加上注释。
  • 可以给Controller类中方法的参数加上@ApiParam()注解,给该参数加上注释

Swagger还拥有测试功能

点开每个接口,都可以进行测试,可以手动传入接口需要的值。

总结

好处:

  1. 可以通过Swagge提供的注解给一些比较难理解的属性或者接口,增加注释信息
  2. 接口文档实时更新
  3. 可以在线测试

注意:出于安全考虑,在正式发布项目的时候,关闭Swagger!

最后修改:2021 年 07 月 18 日 04 : 29 PM
如果觉得我的文章对你有用,请随意赞赏