前后端分离，接口调试利器--Swagger

目录

 

一、背景

二、Swagger使用介绍

三、Swagger环境搭建

---

一、背景

前后端分离时，后端人员往往是要自己独立开发出一个能使用的接口，此时，类似于postman、Swagger、idea插件等等这些api工具就用的上了。当然这篇文章主要介绍Swagger搭建和使用。

环境：SpringBoot + Swagger2

 

二、Swagger使用介绍

1、控制器--Controller中使用Swagger

属性	说明
@Api(tags = "xx管理")	修饰类上，tags标注此类的作用
@ApiOperation(notes="xx", value="xx")	修饰方法上，notes标准方法说明，value标准方法具体作用（增删改查）
@ApiResponse(code=xx, message="xx")	修饰方法上，code响应成功的状态码，message是成功信息

2、DTO传输层Swagger用法

属性	说明
@ApiModelProperty(name="xx", value="xx")	修饰属性，属性说明，name对象属性名称，value对应属性说明
@NotNull(message="xxx不能为空")	修饰属性，表明属性是非空的，必输
@Length(max=xx)	修饰属性，一般为字符，表示最大长度限制

 

例子说明

WordController.java

package com.essm.controller;

import com.essm.entity.WordDO;
import com.essm.remote.WordReqDTO;
import com.essm.remote.WordRspDTO;
import com.essm.service.WordService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

/**
 * 单词控制层
 *
 * @author ：HUANG ZHI XUE
 * @date ：Create in 2020-08-18
 */
@RestController
@Api(tags = "单词管理")
public class WordController {

    @Autowired
    WordService wordService;

    @ApiOperation(notes = "单词管理", value = "单词管理-查询接口")
    @ApiResponse(code = 200, message = "查询成功")
    @PostMapping("/listWordInfo")
    public List<WordRspDTO> listWordInfo(@Validated @RequestBody WordReqDTO reqDto) {
        return wordService.listWordInfo(reqDto);
    }
}

 

WordReqDTO.java

package com.essm.remote;

import io.swagger.annotations.ApiModelProperty;

import javax.validation.constraints.NotNull;

/**
 * 请求通用dto
 *
 * @author ：HUANG ZHI XUE
 * @date ：Create in 2020-08-18
 */
public class WordReqDTO {

    /** 单词编号 */
    @ApiModelProperty(name = "id", value = "单词编号", required = true)
    @NotNull(message = "单词编号不能为空")
    private Integer id;

    /** 用户编号 */
    private Integer trl;

    /** 单词中文 */
    private String chinese;

    /** 单词英文 */
    private String english;

    /** 单词状态位 */
    private Integer sign;

    public WordReqDTO() {
    }

    public WordReqDTO(Integer id, Integer trl, String chinese, String english, Integer sign) {
        this.id = id;
        this.trl = trl;
        this.chinese = chinese;
        this.english = english;
        this.sign = sign;
    }

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public Integer getTrl() {
        return trl;
    }

    public void setTrl(Integer trl) {
        this.trl = trl;
    }

    public String getChinese() {
        return chinese;
    }

    public void setChinese(String chinese) {
        this.chinese = chinese;
    }

    public String getEnglish() {
        return english;
    }

    public void setEnglish(String english) {
        this.english = english;
    }

    public Integer getSign() {
        return sign;
    }

    public void setSign(Integer sign) {
        this.sign = sign;
    }

    @Override
    public String toString() {
        return "WordDO{" +
                "id=" + id +
                ", trl=" + trl +
                ", chinese='" + chinese + '\'' +
                ", english='" + english + '\'' +
                ", sign=" + sign +
                '}';
    }
}

 

三、Swagger环境搭建

1、pom.xml依赖

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

2、加入swagger配置文件SwaggerConfig.java

package com.essm.config;

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger配置
 *
 * @author ：HUANG ZHI XUE
 * @date ：Create in 2020-08-13
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.essm.controller"))
                .paths(PathSelectors.any())
                .build();

    }
    //设置swagger的一些信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger2")
                .description("Restful API接口")
                .version("1.0.1")
                .build();
    }
}

3、如果路径做了拦截，需要放行swagger页面（自己项目比较老，看实际情况加即可）

重心在

    /**
     * 添加静态资源文件，外部可以直接访问地址
     *
     * @param registry
     */
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        //解决静态资源无法访问
        registry.addResourceHandler("/static/**")
                .addResourceLocations("classpath:/static/");
        // 解决swagger无法访问
        registry.addResourceHandler("/swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        // 解决swagger的js文件无法访问
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

配置类全：

package com.essm.config;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.ViewControllerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

import java.io.IOException;

/**
 * @Description
 * 扩展SpringMVC功能
 * 1、固定页面跳转
 * 2、拦截器
 * @Author xuexue
 * @Date 2020/5/19 19:52
 */
@Configuration
public class EssmMvcConfig implements WebMvcConfigurer {

    @Autowired
    private StaticPagePathFinder staticPagePathFinder;

    public void addViewControllers(ViewControllerRegistry registry) {
        registry.addViewController("/essm.html").setViewName("index");
        registry.addViewController("/essm").setViewName("index");


        //addViewControllers可以方便的实现一个请求直接映射成视图，而无需书写controller
        //registry.addViewController(
        // "请求路径").setViewName("请求页面文件路径")
        try{
            for(StaticPagePathFinder.PagePaths pagePaths :staticPagePathFinder.findPath()){
                String urlPath = pagePaths.getUrlPath();
                registry.addViewController(urlPath+".html").setViewName(pagePaths.getFilePath());
                if(!urlPath.isEmpty()) {
                    registry.addViewController(urlPath).setViewName(pagePaths.getFilePath());
                }
            }
        }catch(IOException e){
            throw new RuntimeException("Unable to locate static pages:"+e.getMessage(),e);
        }

    }

    /**
     * 登录拦截器
     *
     * @param registry
     */
    public void addInterceptors(InterceptorRegistry registry) {
        String[] excludes = new String[]{"/login.html", "/login", "/essm", "/header.html", "/essm.html", "/static/**"};
        registry.addInterceptor(new MyInterceptor()).
                addPathPatterns("/**").
                excludePathPatterns(excludes);
    }

    /**
     * 添加静态资源文件，外部可以直接访问地址
     *
     * @param registry
     */
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        //解决静态资源无法访问
        registry.addResourceHandler("/static/**")
                .addResourceLocations("classpath:/static/");
        // 解决swagger无法访问
        registry.addResourceHandler("/swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        // 解决swagger的js文件无法访问
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

4、对应扫描包下建立一个WordController

5、启动项目，项目地址加/swagger-ui.html访问，如图