Swagger介绍及使用
解决前后端联调接口文档问题,当项目更新时,接口文档更新不上,会导致联调出现问题,好的接口文档会加快开发效率,加快前后端联调的速度,当接口更新时,接口文档也能实时更新
目前Swagger在Sping中更名为SpringFox
Swagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档,同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包,docker,node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。
Swagger UI:提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。
Swagger Editor: 类似于markendown编辑器的编辑Swagger描述文件的编辑器,该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。
Swagger Inspector: 感觉和postman差不多,是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求,会返回更多的信息,也会保存你请求的实际请求参数等数据。
Swagger Hub:集成了上面所有项目的各个功能,你可以以项目和版本为单位,将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作,需要注册账号,分免费版和收费版。
Springfox Swagger: Spring 基于swagger规范,可以将基于SpringMVC和Spring Boot项目的项目代码,自动生成JSON格式的描述文件。本身不是属于Swagger官网提供的,在这里列出来做个说明,方便后面作一个使用的展开。
总结
其实归根到底,使用Swagger,就是把相关的信息存储在它定义的描述文件里面(yml或json格式),再通过维护这个描述文件可以去更新接口文档,以及生成各端代码。而Springfox-swagger,则可以通过扫描代码去生成这个描述文件,连描述文件都不需要再去维护了。所有的信息,都在代码里面了。代码即接口文档,接口文档即代码。
链接:https://www.jianshu.com/p/349e130e40d5
在pom文件中引入swagger的pom和swagger-ui的jar包
示例
<dependency>
//Swagger核心jar
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
//SwaggerUI界面
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
使用springfox-swagger-ui的界面
国人开发适合自己人用的增强UI界面
文档地址
pom
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.2</version>
</dependency>
经过测试发现使用knife4j中创建多个分支后去掉默认分支,就是在创建docket时不指定groupName,访问会发生Knife4j文档请求异常经分析,knife4j打开swagger页面后先进行访问default的分支,因为我们没有创建,所以会报异常问题,如果想解决这个问题创建defaultDocket,另一中方式就是指定访问swagger时访问第一个Docket。。。。。。。。。。。。。。。。。。。springfox-swagger-ui不会出现这个问题
关于使用
添加完相关依赖后需要进行对我们的接口进行配置,创建SwaggerConfig的Java文件进行对我的项目进行相关配置
示例:
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createTestApi() {
return new Docket(DocumentationType.SWAGGER_2).groupName("sdd")
.