springboot 接入RESTful 风格的 Web 服务框架 Swagger 生成接口文档-CSDN博客

本文链接：https://blog.csdn.net/Alice_qixin/article/details/105714822

借鉴：https://www.jianshu.com/p/f4fb5e9899fc

前言：作为一个以前后端分离为模式开发小组，我们每隔一段时间都进行这样一个场景：前端人员和后端开发在一起热烈的讨论"哎,你这参数又变了啊","接口怎么又请求不通了啊","你再试试,我打个断点调试一下.."。可以看到在前后端沟通中出现了不少问题。

对于这样的问题,之前一直没有很好的解决方案，直到它的出现，没错...这就是我们今天要讨论的神器:swagger,一款致力于解决接口规范化、标准化、文档化的开源库，一款真正的开发神器。

一：swagger是什么？

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

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

二：为什么要使用swaager?

2.1:对于后端开发人员来说

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

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

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

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

2.2:对于前端开发来说

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

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

2.3：对于测试

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

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

配置信息

pom引入swagger依赖

<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>

配置文件：

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

@EnableSwagger2
@Configuration
public class SwaggerConfig {

    private static final String BASE_PACKAGE = "com.xxx.xxx.xxx.xxx.controller";

    @Bean
    public Docket docket() {
        ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder().title("主数据字典维护 Restful API");

        return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors
                .basePackage(BASE_PACKAGE)).paths(PathSelectors.any()).build().apiInfo(apiInfoBuilder.build());
    }
}

接口配置




@RestController
public class TestController extends AbstractBasicController {

    @Autowired
    private TestService testService;


    @ApiOperation(response = RestDataResponse.class, value = "获取数据")
    @GetMapping("/test")
    public RestDataResponse getTestInfo(Integer id) {
        return newRestDataResponse(testService.selectOne(id));
    }

}

默认的访问地址：ip:port/swagger-ui.html#/

4.2:访问本地链接

http://localhost:8080/swagger-ui.html#/