赞
踩
日常求赞,感谢老板。
欢迎关注公众号:其实是白羊。干货持续更新中......
现在的很多项目都是前后端分离的,后端提供接口,前端调用接口,在这个过程中一般后端会向前端提供一份接口文档,但是随着程序的调整,我们还要不断的去迭代接口文档,最后可能会搞出一堆,写起来比较耗时且在规范性上也很难要求。在这个前提下我们可以选择Swagger加入到我们的项目中。
Swagger提供了很多的功能,其中Swagger UI和Swagger Inspector使用的比较多
我们这里的项目框架是Spring Boot
- <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>
- /**
- * @Description swagger配置文件
- * @Author ZhangLinlu
- * @Date 2020/10/10
- **/
- @EnableSwagger2
- @Configuration
- public class SwaggerConfig {
-
- private ApiInfo apiInfo() {
- return new ApiInfoBuilder()
- // 设置页面标题
- .title("使用swagger2构建后端api接口文档")
- // 设置联系人
- .contact(new Contact("myname", "url", "email"))
- // 描述
- .description("欢迎访问后端接口文档,这里是描述信息")
- // 定义版本号
- .version("1.0").build();
- }
-
- @Bean
- public Docket createRestApi() {
- return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
- //接口所在的包
- .apis(RequestHandlerSelectors.basePackage("com.example.swaggerdemo.controller"))
- .paths(PathSelectors.any()).build();
- }
- }

至此,我们就可以访问http://localhost:8080/swagger-ui.html看到swagger为我们提供的在线调试和在线接口文档的页面了
但是,目前上面的描述信息还不够详细。我们可以通过下面的注解来完善对接口、参数、返回值等的描述
ble data-draft-node="block" data-draft-type="table" data-size="normal" data-row-style="normal">
附3.1:
举个栗子:
- /**
- * @Description 测试接口
- * @Author ZhangLinlu
- * @Date 2020/10/10
- **/
- @Api(tags = "测试接口")
- @RestController
- public class TestController {
-
- @ApiOperation(value = "我是test1接口",notes = "notes:我是test1")
- @ApiImplicitParams(value = {
- @ApiImplicitParam(name = "name",value = "姓名",required = true,paramType = "query",dataType = "String",defaultValue = "zll")
- })
- @GetMapping("test1")
- public Object test1(String name) {
- return "success" + name;
- }
-
- @ApiOperation(value = "我是test2接口",notes = "notes:我是test2")
- @GetMapping("test2")
- public Object test2(TestParamDTO testParamDTO) {
- return "success" + testParamDTO.getName();
- }
- }
-
- /**
- * @Description 测试javabean参数
- * @Author ZhangLinlu
- * @Date 2020/10/10
- **/
- @Data
- @ApiModel(value = "测试javabean参数")
- public class TestParamDTO {
-
- @ApiModelProperty(name = "name",value = "姓名",required = true)
- private String name;
- }

到这里已经完成了整个的整合,前端再让你出接口文档,直接url地址扔给她,潇洒转身离开。程序改动也不用重新写一份,改了哪里注解改一下就行了。
“你这页面好丑啊,接口多了也不好找。。。。”
“线上调试,接口做了鉴权没token怎么办。。。。”
面对这些吐槽,下面介绍一个好看的ui:knife4j(https://gitee.com/xiaoym/knife4j),这是个人维护的ui项目很好的解决了上面的问题
引入knife4j只需要引入相应的依赖,其他的都不用修改,完美兼容
- <dependency>
- <groupId>com.github.xiaoymin</groupId>
- <artifactId>knife4j-spring-boot-starter</artifactId>
- <version>2.0.2</version>
- </dependency>
可以把之前引入的swagger依赖都去掉了,这个依赖包含了所需的swagger依赖
这次访问线上接口文档的地址改成了:http://localhost:8080/doc.html
不仅优化了ui界面,而且在文档管理中为我们提供了全局参数、离线文档等功能,很值得推荐。
文章中的demo我已经上传到了gitee,需要的可以clone看一下:https://gitee.com/zhanglinlu/swagger-demo
点个赞啊亲
如果你认为本文对你有帮助,可以「在看/转发/赞/star」,多谢 如果你还发现了更好或不同的想法,还可以在留言区一起探讨下
欢迎关注公众号:「其实是白羊」干货持续更新中......
Copyright © 2003-2013 www.wpsshop.cn 版权所有,并保留所有权利。