2019独角兽企业重金招聘Python工程师标准>>> 
前言
现代化的研发组织架构中，一个研发团队基本包括了 产品组、后端组、前端组、APP端研发、 测试组、 UI组等，各个细分组织人员各司其职，共同完成产品的全周期工作。如何进行组织架构内的有效高效沟通就显得尤其重要。其中，如何构建一份合理高效的接口文档更显重要。
接口文档横贯各个端的研发人员，但是由于接口众多，细节不一，有时候理解起来并不是那么容易，引起‘内战’也在所难免， 并且维护也是一大难题。
17 年项目使用markdown 文档, 项目大了, 18年转而引用RAP文档;
类似RAP文档管理系统，将接口文档进行在线维护，方便了前端和APP端人员查看进行对接开发 ，但是还是存在以下几点问题：
- 文档是接口提供方手动导入的，静态文档,项目大查阅麻烦；
- 多人开发时,容易造成文档锁定,无法继续编写;
- 维护的难度不小。
- 后端开发人员编写重复,工作量大
- 确实接口测试,一般都是自己下载postman调试接口
Swagger的出现可以完美解决以上传统接口管理方式存在的痛点。
解放后端开发人员,全程自动生成,无需频繁切换,工具,一切都在java中;
本文介绍SpringBoot整合Swagger2的流程。
什么是Swagger
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。
作用
- 接口文档在线生成
- 功能测试
实用语法
@Api：用在类上，说明该类的作用。
@ApiOperation：注解来给API增加方法说明。
@ApiImplicitParams : 用在方法上包含一组参数说明。
@ApiImplicitParam：用来注解来给方法入参增加说明。
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
l code：数字，例如400
l message：信息，例如"请求参数没填好"
l response：抛出异常的类
@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
l @ApiModelProperty：描述一个model的属性
| paramType：指定参数放在哪个地方 |
header：请求参数放置于Request Header，使用@RequestHeader获取 query：请求参数放置于请求地址，使用@RequestParam获取 path：（用于restful接口）-->请求参数的获取：@PathVariable body：（不常用） form（不常用） |
| name：参数名 |
|
| dataType：参数类型 |
|
| required：参数是否必须传 |
true | false |
| value：说明参数的意思 |
|
| defaultValue：参数的默认值 |
简单介绍完毕,开始正式组合搭建了
springboot + swagger 搭建
1. dependency引用
io.springfox
springfox-swagger2
2.9.2
io.springfox
springfox-swagger-ui
2.9.2
com.github.xiaoymin
swagger-bootstrap-ui
1.8.7
2. config配置
package com.xxx.config;
import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
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;
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI //第三方swagger增强API注解
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
/**
* @Author wuxw
* @Description //关于分组接口,可后期根据多模块,拆解为根据模块来管理API文档
* @Date 10:18 2019/3/15
* @Param []
* @return springfox.documentation.spring.web.plugins.Docket
**/
return new Docket(DocumentationType.SWAGGER_2)
.groupName("后台管理接口")
.apiInfo(apiInfo())
.host("localhost:8082")
.select()
.apis(RequestHandlerSelectors.basePackage("com.xx.xx.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("XX项目API")
.description("系统化信息化XX平台,为您提供最优质的服务")
.termsOfServiceUrl("")
.version("1.0")
.build();
}
}
3. 方法注释
划重点: 注解Controller接口方法时,务必指定@GetMappering,@PostMapping等, 否则swagger 会生成多个相同api的接口;
4. 访问入口
如未使用增强ui, 则访问路径为: http://localhost:8080/swagger-ui.html (默认)
增强UI 访问路径: http://localhost:8080/doc.html
其中, 如果使用增强ui, doc.html404 找不到的话, 可修改application类,重载指定方法实现;
package com.xx.xx;
import lombok.extern.slf4j.Slf4j;
import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Slf4j
@SpringBootApplication
@MapperScan("com.xx.xx.*.mapper")
public class SystemApplication implements WebMvcConfigurer {
public static void main(String[] args) {
long beginTime = System.currentTimeMillis();
SpringApplication.run(SystemApplication.class, args);
long endTime = System.currentTimeMillis();
log.error("-----------启动完毕---------;启动耗时(s):"+((endTime-beginTime)/1000));
}
/**
* @Author wuxw
* @Description implements WebMvcConfigurer 该接口,重写addResourceHandlers ,添加swagger2 UI doc样式
* @Date 9:49 2019/3/15
* @Param [registry]
* @return void
**/
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
默认UI界面
增强UI界面
其中, 展开页签功能 更是对开发者来说, 可随意切换接口调试,非常的棒
推荐完毕
增强UI更多功能,欢迎访问官方文档
http://www.xiaominfo.com/swagger-bootstrap-ui/