巢湖网站建设电话,wordpress栏目更改无法显示,企业信息公示管理系统广东,新型互联网项目代理介绍 相信无论是前端还是后端开发#xff0c;都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力#xff0c;经常来不及更新。其实无论是前端调用后端#xff0c;还是后端调用后端#xff0c;都期望…介绍 相信无论是前端还是后端开发都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力经常来不及更新。其实无论是前端调用后端还是后端调用后端都期望有一个好的接口文档。但是这个接口文档对于程序员来说就跟注释一样经常会抱怨别人写的代码没有写注释然而自己写起代码起来最讨厌的也是写注释。所以仅仅只通过强制来规范大家是不够的随着时间推移版本迭代接口文档往往很容易就跟不上代码了。 发现了痛点就要去找解决方案。解决方案用的人多了就成了标准的规范这就是Swagger的由来。通过这套规范你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具就可以做到生成各种格式的接口文档生成多种语言的客户端和服务端的代码以及在线接口调试页面等等。这样如果按照新的开发模式在开发新版本或者迭代版本的时候只需要更新Swagger描述文件就可以自动生成接口文档和客户端服务端代码做到调用端代码、服务端代码以及接口文档的一致性。
Swagger官网https://swagger.io/ 框架说明 现在SWAGGER官网主要提供了几种开源工具提供相应的功能。可以通过配置甚至是修改源码以达到你想要的效果 Swagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包dockernode等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。
Swagger UI:提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。
Swagger Editor: 类似于markendown编辑器的编辑Swagger描述文件的编辑器该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。
Swagger Hub集成了上面所有项目的各个功能你可以以项目和版本为单位将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作需要注册账号分免费版和收费版。
PS
Springfox Swagger: Spring 基于swagger规范可以将基于SpringMVC和Spring Boot项目的项目代码自动生成JSON格式的描述文件。本身不是属于Swagger官网提供的在这里列出来做个说明方便后面作一个使用的展开。其实swagger是有两个版本的区别还挺大的一个是swagger-ui也就是swagger1;还有一个是springfox-swagger也就是swagger2;
总结
Swagger 是一个规范和完整的框架用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。使用Swagger就是把相关的信息存储在它定义的描述文件里面yml或json格式再通过维护这个描述文件可以去更新接口文档以及生成各端代码。而Springfox-swagger,则可以通过扫描代码去生成这个描述文件连描述文件都不需要再去维护了。所有的信息都在代码里面了。代码即接口文档接口文档即代码。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法参数和模型紧密集成到服务器端的代码允许API来始终保持同步。
作用
接口的文档在线自动生成功能测试
SpringBoot集成Swagger
初始实现步骤
1. 添加Maven依赖
dependencygroupIdio.springfox/groupIdartifactIdspringfox-swagger2/artifactIdversion2.9.2/version
/dependency
dependencygroupIdio.springfox/groupIdartifactIdspringfox-swagger-ui/artifactIdversion2.9.2/version
/dependency
2. 编写HelloController测试确保运行成功
RestController
public class SwapperControllerTest {GetMapping(/swapperTest)public String swapperTest(String name){return name;}
}
3. 编写一个配置类-SwaggerConfig(或者通过在项目启动类上加EnableSwagger2注解)来配置 Swagger
Configuration //配置类
EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {}
启动类加注解 以上方法2选1即可
4. 访问测试 http://localhost:8080/swagger-ui.html 可以看到swagger的主界面 注意:
如果启动报错空指针是因为springboot2.6.0中将SpringMVC 默认路径匹配策略从AntPathMatcher 更改为PathPatternParser导致出错可以在启动类上加上EnableWebMvc注解或者在配置中切换为原先的AntPathMatcherspring.mvc.pathmatch.matching-strategyant_path_matcher 配置Swagger
1. Swagger实例Bean是Docket所以通过配置Docket实例来配置Swagger
Bean //配置docket以配置Swagger具体参数
public Docket docket() {return new Docket(DocumentationType.SWAGGER_2);
}
2. 可以通过apiInfo()属性配置文档信息
private ApiInfo createApiInfo(){Contact contact new Contact(testName,www.baidu.com,277277727727163.com);return new ApiInfo(Swagger学习, // 标题学习演示如何配置Swagger, // 描述v1.0, // 版本http://ape.com, // 组织链接contact, // 联系人信息Apach 2.0 许可, // 许可许可链接, // 许可连接new ArrayList()// 扩展);
3. Docket 实例关联上 apiInfo()
Bean
public Docket docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
4. 重启项目访问测试 http://localhost:8080/swagger-ui.html 看下效果 配置扫描接口
1. 构建Docket时通过select()方法配置怎么扫描接口
//配置swapper主页信息Beanpublic Docket docket(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(createApiInfo()).select()// 通过.select()方法去配置扫描接口,RequestHandlerSelectors配置如何扫描接口.apis(RequestHandlerSelectors.basePackage(com.ape.springboot_swapper.controller)).build();}
2. 重启项目测试由于我们配置根据包的路径扫描接口所以我们只能看到一个类 3. 除了通过包路径配置扫描接口外还可以通过配置其他方式扫描接口这里注释一下所有的配置方式
any() // 扫描所有项目中的所有接口都会被扫描到
none() // 不扫描接口
// 通过方法上的注解扫描如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class? extends Annotation annotation)
// 通过类上的注解扫描如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation(final Class? extends Annotation annotation)
basePackage(final String basePackage) // 根据包路径扫描接口
4. 除此之外我们还可以配置接口扫描过滤
// 配置如何通过path过滤,即这里只扫描请求以/apesource开头的接口
.paths(PathSelectors.ant(/apesource/**))
5. 这里的可选值还有
any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制
配置API分组
1. 如果没有配置分组默认是default。通过groupName()方法即可配置分组 Bean
public Docket docket(Environment environment) {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName(hello) // 配置分组// 省略配置....
}
2. 重启项目查看分组 3. 如何配置多个分组配置多个分组只需要配置多个docket即可
// 多个分组Bean Docket docket2(){return new Docket(DocumentationType.SWAGGER_2).groupName(test2);}Bean Docket docket3(){return new Docket(DocumentationType.SWAGGER_2).groupName(test3);}Bean Docket docket4(){return new Docket(DocumentationType.SWAGGER_2).groupName(test4);}Bean Docket docket5(){return new Docket(DocumentationType.SWAGGER_2).groupName(test5);} 拓展其他皮肤
我们可以导入不同的包实现不同的皮肤定义
1.默认的访问 http://localhost:8080/swagger-ui.html
dependencygroupIdio.springfox/groupIdartifactIdspringfox-swagger-ui/artifactIdversion2.9.2/version
/dependency
bootstrap-ui 访问 http://localhost:8080/doc.html
dependencygroupIdcom.github.xiaoymin/groupIdartifactIdswagger-bootstrap-ui/artifactIdversion1.9.1/version
/dependency
常用注解
swagger通过注解生成接口文档包括接口名、请求方法、参数、返回信息的等等。
1. Api修饰整个类描述Controller的作用
语法Api(tags说明该类的作用可以在UI界面上看到的注解value /类的访问路径,
description 类的文字描述)
2. ApiOperation描述一个类的一个方法说明方法的作用
语法ApiOperation(value “接口说明”, httpMethod “接口请求方式”, response “接口返回参数类型”, notes “接口发布说明”
3. ApiImplicitParam一个请求参数
语法ApiImplicitParam(required “是否必须参数”, name “参数名称”, value “参数具体描述”,dateType变量类型”,paramType请求方式”
· header -- 请求参数的获取RequestHeader
· query -- 请求参数的获取RequestParam
· path用于restful接口-- 请求参数的获取
PathVariable
· body不常用
· form不常用 4. ApiImplicitParams 多个请求参数
5. ApiParam单个参数描述
语法ApiParam(required “是否必须参数”, name “参数名称”, value “参数具体描
述”,dateType变量类型”,paramType请求方式”
6. ApiResponseHTTP响应其中1个描述,响应配置
语法ApiResponse(code 400, message Invalid user supplied)
7. ApiResponsesHTTP响应整体描述
语法ApiResponses({ ApiResponse(code 400, message Invalid Order) })
8. ApiModel用对象实体来作为入参
9. ApiProperty用对象接实体收参数时描述对象的一个字段
10. ApiIgnore使用该注解忽略这个API
11. ApiError 发生错误返回的信息
测试
创建实体类与测试类并使用注解
NoArgsConstructor
AllArgsConstructor
Data
ApiModel(value 控制器方法返回值,description 自定义结果集)
public class Result {ApiModelProperty(name state,value 结果集状态,example true)private boolean state;ApiModelProperty(name message,value 消息,example abc)private String message;ApiModelProperty(name date,value 数据集)private Object date;
}
RestController
Api
RequestMapping(/user)
public class SwapperControllerTest02 {GetMapping(/findByName)ApiOperation(value 根据用户名查询)public Result findByName(String name){if(name.equals(aaa)){return new Result(true,成功,aaa);}else {return new Result(false,失败,bbb);}}
}
使用注解后效果如下 Swagger会自动识别接口请求方式参数类型个数返回结果等信息
点击Try it out测试接口 输入对应参数点击执行、 成功后返回相关信息
