三分钟生成接口API文档，让前后端交互不在难

工作中经常需要各种调试，前后端接口定义，测试人员测试，三方接入等实际场景中我们需要大量的输出API文档，既费时又费力。下面我将介绍一个开源工具Swagger UI，结合 spring boot 给大家讲解。

Swagger UI简介

Swagger UI 在没有任何实现逻辑的情况下可视化API的资源交互。它是根据OpenAPI（称为Swagger）规范自动生成的，可视化文档使后端实现和客户端使用变得容易。

image.png

第一步 环境配置

添加Swagger UI依赖

我们需要将Swagger UI的统一版本依赖加入到项目的pom.xml文件内，如下所示：

        
            io.springfox
            springfox-swagger2
            2.6.1
        
         
        
            io.springfox
            springfox-swagger-ui
            2.6.1
        

配置Swagger的Bean

package com.xiaoming.tools.commons.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;

/**
 * @Description: swagger-ui 配置
 * @Author: xiaoMing
 * @Date: 2019/11/19 10:58
 */
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xiaoming.tools.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("这是标题")
                .description("这里是一段描述，https://www.jianshu.com/u/85117e1faa39")
                .termsOfServiceUrl("https://www.jianshu.com/u/85117e1faa39")
                .version("1.0")
                .build();
    }

}

@Configuration会被项目启动加载为配置类,等同于XML中配置的beans；
@Bean标注方法等同于XML中配置的bean。

注：basePackage的扫描路径是controller层

配置启动类

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class APP{
 
    public static void main(String[] args) {
        SpringApplication.run(APP.class, args);
    }
}

在启动类上上注解@EnableSwagger2，代表开启swagger

第二步 使用

在controller上添加注解

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @Description: swagger-ui demo
 * @Author: xiaoming
 * @Date: 2019/11/19 11:11
 */
@RestController
@RequestMapping(value = "/demo")
@Api(value = "demo")
public class DemoController {
    @ApiOperation(value = "获取Model", notes = "根据实体id获取")
    @PostMapping(value = "/getModel")
    public Object getModel(@RequestBody ModelVO demo) {
        return new ModelVO(1, 1);
    }
}

@Api用于controller类上
@ApiOperation用在controller的方法上

在实体类上添加注解

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

/**
 * @Description: 实体对象
 * @Author: xiaoming
 * @Date: 2019/11/19 11:14
 */
@ApiModel(value = "ModelVO对象",description = "展示对象")
public class ModelVO {
    @ApiModelProperty(value = "主键")
    private Integer id;
    @ApiModelProperty(value = "姓名",name = "id",required = true)
    private String name;
    @ApiModelProperty(value="状态：0启动，1停用",name="state",example="1")
    private Integer state;
    ...
}

@ApiModel用在返回对象类上

• value可为空 默认为class名
• description 可为空 默认''

@ApiModelProperty用在出入参数对象的字段上

• value 接收参数的意义描述
• name 接收参数名
• required 参数是否必填(true 必填，false 非必填)
• example 举例说明

第三步 测试

启动项目访问 http://localhost:8080/swagger-ui.html
至此全部完毕

效果.png

本文首发于公众号「 晓明的30天实验室 」，关注公众号，即可获得更多相关教程。

如果你觉得文章还不错，请大家点赞分享下。你的肯定是我最大的鼓励和支持。