文档交互Swagger

文档交互Swagger

文章目录

1、简介

• 前后端分离：Vue+SpringBoot

后端时代：

前端只用管理静态页面，将整个html交给后端；后端的模板引擎JSP， 后端 是主力。

前后端分离时代：

后端：后端控制层，服务层，数据访问层

前端：前端控制层，视图层

前端可以伪造后端的数据，通过json跟后端进行交互。现在已经不需要后端，前端工程依然可以运行起来。

前后端交互方式：API接口

前后端相对独立，松耦合

前后端甚至可以部署到不同的服务器上面

产生的问题：

前后端集成联调，前端人员和后端人员无法做到及时协商以便尽快解决问题，最终将导致问题集中爆发；简单来讲，也就是前端不知道后端将提供给前端的接口名字以及后端将传送给前端的数据以及数据类型。。

解决方案：

首先应该指定计划，实时更新后端提供给前端的最新API，来降低集成的风险。

比如早些年，会指定word计划文档

前后端分离：

前端测试后端的接口：postman

后端提供接口，需要实时更新最新的消息以及改动

不太方便：这样需要特定去下载安装postman,但是笔者觉得国产接口测试工具Apiposth还是比较好用的，相对于postman来说

2、Swagger

• RestFull Api文档在线自动生成工具==》Api文档与API接口定义同步更新
• 直接运行，可以在线测试API接口
• 支持多种语言：java , Php

在项目中使用swagger需要导包

• swagger2
• ui

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

这里注意Springboot2.6版本之后和Swagger版本不匹配导致项目出错，降低Springboot版本就好啦，这里用2.1.7.RELEASE版本

<version>2.1.7.RELEASE</version>

3.Springboot集成swagger

3.1、编写一个hello工程

@RestControllerpublicclassHelloController{@GetMapping("/hello")publicStringhello(){return"haohao";}}

3.2、配置Swagger

@Configuration// 标明是配置类@EnableSwagger2//开启swagger功能publicclassSwaggerConfig{/**
    * 配置了Swagger 的Dockerd的bean实例
     *
    */@BeanpublicDocketdocket(){//该方法返回对象为Docket,并将该对象注入到Bean里面//设置要显示的swagger环境Profiles profiles =Profiles.of("dev","test");//获取项目的环境：//通过environment.acceptsProfiles判断是否处在自己设定的环境中//如果系统检测到当前环境为dev或者test则flag为true,否则为flase//        boolean flag = environment.;returnnewDocket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("吉吉国王")//enable 是否开启swagger，如果为false,swagger不能在浏览器中访问//.enable(false).select()//RequestHandlerSelectors:配置要扫描接口的方式//basePackage：指定要扫描的包//any():扫描全部//none():不扫描//withClassAnnotation:扫描类上的注解，参数是一个注解的反射对象//withMethodAnnotation: 扫描方法上的注解.apis(RequestHandlerSelectors.basePackage("com.hh.swagger.controller"))//paths():要过滤什么路径//.paths(PathSelectors.ant("/hh/**")).build();}/**
     * 配置Swagger信息=apiInfo
     */publicApiInfoapiInfo(){//作者信息Contact contact =newContact("吉吉国王","https://blog.csdn.net/qq_56265207?spm=1000.2115.3001.5343","[email protected]");returnnewApiInfo("吉吉国王的SwaggerAPI文档","落日很温柔，你也一样","v2.0","https://blog.csdn.net/qq_56265207?spm=1000.2115.3001.5343",
                contact,"Apache 2.0","https://www.apache.org/licenses/LICENSE-2.0",newArrayList());}}

测试：

Swagger UI

解释：

• 配置扫描接口Docket.select()
• Docket.apis(RequestHandlerSelectors.basePackage(“com.hh.swagger.controller”))表示只扫描包com.hh.swagger.controller，所以当我们打开网址Swagger UI可以看到只有一个接口信息
• enable 配置是否启动swagger

问题：我只希望我的swagger在生产环境中使用，在发布的时候不使用？

• 判断是不是生产环境 flag=false
• 注入enable(flag)

进行多配置的方法:

1.第一套环境：在resources下面新建生产环境文件application-dev.properties 并输入以下内容：

 server.port=8081

2.第二套环境，在resources下面新建生产环境文件application-pro.properties 并输入以下内容：

server.port=8082

3.在文件SwaggerConfig中按如下设置：

//设置要显示的swagger环境Profiles profiles =Profiles.of("dev","test");

4.指定当前环境

application.properties中输入以下代码

spring.profiles.active=dev  
//指定当前环境为dev

3.3、配置API文档的分组

1.只有一个分组：在文件swaggerconfig.java中一定位置加入以下代码

Docket.groupName("吉吉国王")

2.存在多个分组时，一个Docket对象代表一个祖，创建多个对象就会有多个组

//多个组@BeanpublicDocketdocket1(){returnnewDocket(DocumentationType.SWAGGER_2).groupName("A");//第一个组}@BeanpublicDocketdocket2(){returnnewDocket(DocumentationType.SWAGGER_2).groupName("B");//第二个组}@BeanpublicDocketdocket3(){returnnewDocket(DocumentationType.SWAGGER_2).groupName("C");//第三个组}

3.4、实体类配置

1、创建一个User类

@ApiModel("用户实体类")//给实体类的文档注释publicclassUser{@ApiModelProperty("用户名")//给属性的文档注释publicString username;@ApiModelProperty("密码")publicString password;}

2、修改controller

@RestControllerpublicclassHelloController{@GetMapping("/hello")publicStringhello(){return"hello";}//只要我们的接口中，返回值存在实体类，它就会被扫描到Swagger中@PostMapping("/user")publicUseruser(){returnnewUser();}//Operation接口,不是放在类上，而是放在方法上@ApiOperation("hello控制类")@GetMapping("/hello2")publicStringhello2(@ApiParam("这是用户名")String username){//@ApiParam("用户名")为参数的注释return"hello"+username;}}

总结：

• 我们可以通过Swagger给一些比较难以理解的属性或者接口，增加注释信息
• 接口文档实时更新
• 可以在线测试
• 注意点：在正式发布的时候，关闭swagger.出于安全考虑，节省内存。