Swagger

2023-10-22 09:33:10

前言

现在很多项目都开始使用前后端分离的架构方式了，前后端分离带来诸多好处的同时，也面临了一些问题，比如前后端开发人员的协同问题。

之前一般是通过文档的形式来定义接口，然后前后端开发人员根据接口去各自开发，但是测试的时候往往会发现有对应不上的情况！

前端添加一个字段，后端则可能修改一系列的方法，这种情况带来了很大的麻烦，因此Swagger应运而生！

Swagger 概念

Swagger 使用场景

Swagger 配置-文档信息

Swagger 配置-接口扫描/过滤

Swagger 配置-分组

Swagger 配置-API注解

使用 Swagger测试接口

Swagger 概念

Swagger主要应用于前后端分离项目的协同开发，通过简单易用的配置，即可实现接口信息文档的实时更新，使得开发更见高效和便捷！

Swagger 使用场景

从开发的角度，这是对于前后端分离而且前后端人员分离的情况的！

如果是前后端分离，但是前后端人员不分离、甚至就是一个人承包了前后端，那实属没必要了~~~

从项目周期的角度，Swagger 在开发和测试时使用，上线则需要关闭。

Swagger 配置

1. 添加依赖包：swagger2、swagger-ui

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->

<dependency>

  <groupId>io.springfox</groupId>

  <artifactId>springfox-swagger2</artifactId>

  <version>2.9.2</version>

</dependency>


<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->

<dependency>

  <groupId>io.springfox</groupId>

  <artifactId>springfox-swagger-ui</artifactId>

  <version>2.9.2</version>

</dependency>

添加配置类，并开启Swagger

package com.hwl.swgger01.config;

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2 //并开启Swagger
public class SwaggerConfig {
}

完成上门两步已经能使用Swagger了，非常简单。

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

Swagger提供的界面有四个信息模块，如上图。

配置Swagger

实际开发中，我们一般不使用默认的配置，而是根据需要进行自定义自己的配置

Swagger的配置主要使用Docket这个实例提供的接口进行配置，从而实轻松现来接管默认配置。

注入配置实例，并修改Swagger信息

package com.hwl.swgger01.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    //配置并注入swagger的Docket实例,接管默认的配置信息
    @Bean
    public Docket docket(){
        return new Docket( DocumentationType.SWAGGER_2 ) //参数 DocumentationType：SWAGGER_12/SWAGGER_2/SPRING_WEB
                .apiInfo( setApiInfo() );
    }

    //配置swagger的apiInfo,参考默认配置修改
    private ApiInfo setApiInfo(){

        Contact contact = new Contact( "工程师01","hello.com","yunnanhwl@163.com" );//作者信息
        return new ApiInfo(
                "我的标题你做主",
                "swagger有点好用",
                "1.0",
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

}

运行查看修改结果：

自定义配置扫描接口

默认的配置是扫描出全部的接口的，例如springBoot默认的错误页面的接口。有时候我们只希望扫描自己想要的接口，这种情况也是通过Docket对象来设置：

 //配置并注入swagger的Docket实例,接管默认的配置信息
    @Bean
    public Docket docket(){
        return new Docket( DocumentationType.SWAGGER_2 ) //参数 DocumentationType：SWAGGER_12/SWAGGER_2/SPRING_WEB
                .apiInfo( setApiInfo() )
                .select()
                .apis( RequestHandlerSelectors.basePackage("com.hwl.swgger01.controller") ) //配置扫描包
                .build();
    }

现在访问只有我们指定包下面的接口了：

通过源码发现这里的扫描策略有以下几种

any //扫描全部
none //都不扫描
withMethodAnnotation //扫描方法上的注
withClassAnnotation //扫描类上的注解，参数,例子:RestController.calss就只会扫描这样的类输出api

以上我们是通过Docket对象的apis来设置扫描哪些包，但有时候我们需要的包下面有些类或接口又是不需要扫描的，这时候需要使用过滤：

.apis() //配置扫描哪些包
.paths（）//配置哪些需要过滤

Swagger的内置开关

Swagger是开发提供了方便，但是一旦产品上线，测需要去掉Swagger，除了直接的代码摘除，其实Swagger提供了接口用来直接关闭：

 .enable( flag ) //flag为false则关闭Swagger

一般会根据项目的环境来判断是否开启，当环境为开发、测试环境时开启：

分组协同开发

.groupName("Group01")

各组来实现自己的Docket配置，从而实现各组的实际对外显示情况：

　　//配置并注入swagger的Docket实例,接管默认的配置信息
    @Bean
    public Docket docket(){
        return new Docket( DocumentationType.SWAGGER_2 ) //参数 DocumentationType：SWAGGER_12/SWAGGER_2/SPRING_WEB
                .apiInfo( setApiInfo() )
                .groupName("Group01")
                .select()
                .apis( RequestHandlerSelectors.basePackage("com.hwl.swgger01.controller") ) //配置扫描哪些
                .build();
    }

    @Bean
    public Docket docket1(){
        return new Docket( DocumentationType.SWAGGER_2 )
                .apiInfo( setApiInfo() )
                .groupName("Group02");
    }

显示如下：

实体类

在前后端分离协同开发中，除了需要沟通接口外，实体类也是很重要的。

使用Swagger后，只要扫描显示的接口中，返回值带有某个实体类，那么该实体类会自动被Swagger加入到module中显示出来：

返回值：

 @RequestMapping("/getUser")
    public User hello(){
        return new User( "lihua","123456" );
    }

Swagger自动显示相关的实体：

此外，为了Swagger文档的友好性，Swagger还提供了一些注解来对类、方法、字段等进行一个额外的注释说明：

如：

@ApiModel("用户信息") 用来标注解释实体类，访问swagger时讲看到注释信息，提供了一定的友好度。

使用Swagger进行接口测试

swagger还直接提供了接口的测试功能，非常方便！

码农公寓

相关文章