Spring Boot整合Swagger

 

一、Swagger简介

Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器。

这个解释简单点来讲就是说，swagger是一款可以根据resutful风格生成的生成的接口开发文档，并且支持做测试的一款中间软件。

 

二、为什么要使用Swagger

1. 对于后端开发人员来说

• 不用再手写WiKi接口拼大量的参数，避免手写错误

• 对代码侵入性低，采用全注解的方式，开发简单

• 方法参数名修改、增加、减少参数都可以直接生效，不用手动维护

• 缺点：增加了开发成本，写接口还得再写一套参数配置

 

2. 对于前端开发来说

• 后端只需要定义好接口，会自动生成文档，接口功能、参数一目了然

• 联调方便，如果出问题，直接测试接口，实时检查参数和返回值,就可以快速定位是前端还是后端的问题

 

3. 对于测试

• 对于某些没有前端界面UI的功能，可以用它来测试接口

• 操作简单，不用了解具体代码就可以操作

• 操作简单，不用了解具体代码就可以操作

 

三、集成Swagger

1. 添加Swagger依赖

<!-- Swagger API文档 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

 

2. 创建Swagger配置文件

import lombok.Getter;
import lombok.Setter;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;

/**
 * swagger配置
 *
 * @Author: 
 * @CreateTime: 2021-06-19
 */
@Setter
@Getter
@Configuration
@ConfigurationProperties(prefix = "swagger")
public class SwaggerProperties {

    /**
     * 是否开启Swagger
     */
    private Boolean enable = true;

    /**
     * 文档标题
     */
    private String title = "智能后台管理";

    /**
     * 文档描述
     */
    private String description = "简单描述";

    /**
     * 文档版本
     */
    private String version = "1.0";

    /**
     * 服务条款
     */
    private String termsOfServiceUrl = "服务条款";

    /**
     * 许可证
     */
    private String license;

    /**
     * 许可证地址
     */
    private String licenseUrl;

    /**
     * 作者信息
     */
    private Contact contact = new Contact();

    @Setter
    @Getter
    public static class Contact {
        /**
         * 作者
         */
        private String name;

        /**
         * 个人网站
         */
        private String url;

        /**
         * 邮箱
         */
        private String email;
    }

}

 

3. 创建Swagger配置类

import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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 static springfox.documentation.builders.RequestHandlerSelectors.withMethodAnnotation;

/**
 * Swagger2Config
 *
 * @Author: 
 * @CreateTime: 2020-11-25
 */
@Configuration
@EnableSwagger2
@Slf4j
@Import(BeanValidatorPluginsConfiguration.class)
public class Swagger2Config {

    /**
     * 系统管理
     *
     * @param swaggerProperties swagger配置
     * @return Docket
     */
    @Bean("system")
    public Docket system(SwaggerProperties swaggerProperties) {
        // 指定规范，这里是SWAGGER_2
        return new Docket(DocumentationType.SWAGGER_2)
                // 设定Api文档头信息，这个信息会展示在文档UI的头部位置
                .apiInfo(apiInfo(swaggerProperties))
                // 是否开启Swagger(生产环境建议关闭，避免接口暴露)
                .enable(swaggerProperties.getEnable())
                .groupName("系统管理")
                .select()
                // 添加过滤条件，谓词过滤predicate，这里是自定义注解进行过滤
                .apis(withMethodAnnotation(ApiOperation.class))
                //.apis(RequestHandlerSelectors.basePackage("com.ai.controller"))
                // 这里配合@ComponentScan一起使用，又再次细化了匹配规则(当然，我们也可以只选择@ComponentScan、paths()方法当中的一中)
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * Api文档头信息
     *
     * @param swaggerProperties 配置
     * @return ApiInfo 数据
     */
    private ApiInfo apiInfo(SwaggerProperties swaggerProperties) {
        SwaggerProperties.Contact contact = swaggerProperties.getContact();
        return new ApiInfoBuilder()
                .title(swaggerProperties.getTitle())
                .description(swaggerProperties.getDescription())
                .termsOfServiceUrl(swaggerProperties.getTermsOfServiceUrl())
                .contact(new Contact(contact.getName(), contact.getUrl(), contact.getEmail()))
                .version(swaggerProperties.getVersion())
                .build();
    }
}

 

4. 编写测试类

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;

import java.util.HashMap;
import java.util.Map;

/**
 * UserController
 *
 * @Author: 
 * @CreateTime: 2021-06-19
 */
@Api(tags = "用户管理")
@Controller
@RequestMapping("/user")
public class UserController {

    @ApiOperation("获取用户信息")
    @GetMapping("/get/{id}")
    public Map<String, Object> get(@PathVariable String id){
        Map<String, Object> map = new HashMap<>();
        map.put("id", id);
        map.put("name", "yongge");
        return map;
    }
}

 

 

访问：http://127.0.0.1:8765/swagger-ui/

 

四、Swagger常用注解介绍

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看到，所以不需要配置"

@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · div（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值

@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性