【机房报修管理系统】后端篇（八）配置接口管理利器——Swagger2

时间 2021-01-16 标签 SpringBoot Swagger2 接口

一、前情提要

在上一篇文章中，我们自定义了一个JSON工具类以及解决当JSON数据为空时出现Null变为""的问题，这一次我们来配置接口管理利器——Swagger2。

二、任务详情

使用Maven导入Swagger2
创建配置类配置Swagger2

三、相关介绍

1.什么是Swagger2？

Swagger2是一个开源框架，用于记录RestFul接口，生成API文档。在《维基百科——Swagger》这样写到：

Swagger is an open-source software framework backed by a large ecosystem of tools that helps developers design, build, document, and consume RESTful Web services. While most users identify Swagger by the Swagger UI tool, the Swagger toolset includes support for automated documentation, code generation, and test-case generation.

Swagger是一个开源软件框架，由大型工具生态系统支持，可帮助开发人员设计，构建，记录和使用RESTful Web服务。虽然大多数用户通过Swagger UI工具识别Swagger，但Swagger工具集包括对自动化文档，代码生成和测试用例生成的支持。

在Web开发当中，身为后端，总少不了和前端打交道，而交流接口就是一个痛点，如果只有一两个接口还好，但开发当中至少会有十个以上的接口，你得要一个个接口和前端开发人员交接，说明这个接口有什么作用，需要带什么参数，会返回什么内容，这样一个个接口和前端开发人员交接是比较麻烦的，再加上一个接口做出来，总得需要测试，最传统的测试就是针对每个接口做一个请求代码，先进一点就是使用POSTMAN对接口进行请求，但是你还是得要手动输入参数，比较麻烦。
而Swagger2就解决了这些难题，你只需要在后端写好接口需要的参数即可（其实这也是Swagger2的缺点，代码入侵性太高），前端开发人员只需要访问Swagger2的地址，在网页上就能够清楚地看到有什么接口,需要带什么参数，还能够发送请求测试接口。这样和前端开发人员交流接口的时候，只需要把Swagger2地址发过去即可。
我项目的Swagger2文档：点我跳转

四、实践操作

1.使用`Maven`导入`Swagger2`

在pom.xml中导入编写以下代码

<!-- swagger2 配置 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.4.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.4.0</version>
        </dependency>

2.创建配置类`Swagger2Config`

在com.repairsystem.config中创建配置类Swagger2Config

package com.repairsystem.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

/** * @author CheungChingYin * @date 2019/1/9 * @time 15:35 */
@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket createRestApi(){
        // 为swagger添加header参数可供输入
        ParameterBuilder userTokenHeader = new ParameterBuilder();
        ParameterBuilder userIdHeader = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        //这里是每个接口的hearder都设置参数Token
        userTokenHeader.name("headerUserToken").description("userToken")
                .modelRef(new ModelRef("string")).parameterType("header")
                .required(false).build();
        userIdHeader.name("headerUserId").description("userId")
                .modelRef(new ModelRef("string")).parameterType("header")
                .required(false).build();
        pars.add(userTokenHeader.build());
        pars.add(userIdHeader.build());

        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.repairsystem.web.controller"))
                .paths(PathSelectors.any()).build()
                .globalOperationParameters(pars);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 设置页面标题
                .title("机房报修系统后台API")
                // 设置联系人
                .contact(new Contact("CheungChingYin-张正贤", "https://blog.csdn.net/qq_33596978", "[email protected]"))
                // 描述
                .description("欢迎访问机房报修系统接口文档")
                // 定义版本号
                .version("1.0").license("MIT").build();
    }

}

3.测试Swagger2

运行项目，访问http://localhost:8081/swagger-ui.html#/，由于没有编写接口，所以没有接口显示出来。

到这里，配置Swagger2已经完成了。如果您对次篇文章有疑问，可以在文章下方留言，谢谢您的阅读。如对【机房报修管理系统】系列文章有兴趣，可以关注或收藏我的文章，您的支持是我最大的动力，我会尽快推出下一期内容，敬请期待。

【机房报修管理系统】后端篇（八） 配置接口管理利器——Swagger2