自动生成api文档的工具-----swagger

前言

在几年前 我们写一个前后端分离的web项目的时候 常常会碰到一些问题， 比如说你后端前端的交互产生了问题 前端需要的数据和你后端数据库里面的数据产生偏差 或者是前端后端不知道怎么进行联调 就会导致很多的问题，这个时候我们就需要实时的来更新api文档以实现降低风险，但是如果工程量变大了 比如是几千人来开发一个项目 一个文档几千个人用 这个时候效率肯定是很低的 所以 我们就引入了swagger

swagger是干什么的？

我们是为了能解决前后端分离 产生的交互问题而引入的swagger所以他也旨在解决前后端产生的交互问题。解决的办法就是管理好api文档 因为前后端交互的很大一部分就是api文档。他的好处就是能直接运行 在线测试api接口 这样我们甚至能把前后端部署在不同的服务器上面。

怎么使用swagger？

首先需要导入依赖

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swaggerui
-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>

启动的时候可能会有空指针异常 这个时候需要将springboot的版本降下来

<version>2.5.7</version>

降到2.5.7就ok了
然后启动就能看到这个UI界面了
http://localhost:8080/swagger-ui.html#/hello

这个界面会显示你端口号下面的请求，比如说hello请求 这个表示hello这个controller层里面的接口 你可以通过swagger的UI界面看到这个接口究竟实现了那些功能，以方便前端人员使用。

设置API文档的属性

在swagger里面的bean实例是docket 所以我们要是想要改变swagger的信息 只需要更改这个bean实例就好了 我们在swagger的配置类里面去生成一个新的docket给这个docket附上你希望的初始值 就能实现 更改 这个文档的内容。

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket docket(){
        return  new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }
    private ApiInfo apiInfo(){

        Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");

        return new ApiInfo(
                "Swagger学习",
                "学习演示如何配置Swagger",
                "v1.0",
                "http://terms.service.url/组织链接",
                contact,
                "Apach 2.0 许可",
                "许可链接",
                new ArrayList<>()
        );

    }
}

这样 我们把这个bean注册到了spring容器里面 然后就可以使用我们自己设置的信息了 现在再访问这个链接 点我 http://localhost:8080/swagger-ui.html 就会看到我们自己设置的样式

主要是一定要记得把这个docket用bean注册到 spring容器里面去 还有就是info的信息也要放到docket里面去。

多人协作开发

api文档最大的好处就是能实现多人协作开发 我们可以使用不同的docket来表示不同的人所开发的不同的功能 我们可以使用多个docket 然后给这些docket来重命名 最后限定只能扫描到的controller层 就ok了。
pyy环境

ljc环境

结尾

我们使用swagger可以解决代码量比较庞大的项目 的api问题 使用起来也是相对比较简单。