Spring Boot优雅整合Swagger2,主动生成在线文档
日常求赞,感激老板。
欢送关注公众号:其实是白羊。干货继续更新中……
一、前言
当初的很多我的项目都是前后端拆散的,后端提供接口,前端调用接口,在这个过程中个别后端会向前端提供一份接口文档,然而随着程序的调整,咱们还要一直的去迭代接口文档,最初可能会搞出一堆,写起来比拟耗时且在规范性上也很难要求。在这个前提下咱们能够抉择Swagger退出到咱们的我的项目中。
Swagger提供了很多的性能,其中Swagger UI和Swagger Inspector应用的比拟多
- Swagger UI:提供了一个UI页面形容我的项目中的接口(包含接口含意、uri、办法、参数、返回值和字段含意等)
- Swagger Inspector:提供了在线对接口进行测试的性能
二、集成Swagger
咱们这里的我的项目框架是Spring Boot
1.引入依赖
<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>
2.配置类
/**
* @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为咱们提供的在线调试和在线接口文档的页面了
然而,目前下面的形容信息还不够具体。咱们能够通过上面的注解来欠缺对接口、参数、返回值等的形容
3.罕用注解
注解 | 标注地位和含意 | 属性以及取值含意 |
---|---|---|
@Api | 标注在接口类上,示意对此类接口的形容 | tags=”阐明此类下接口的含意” |
@ApiOperation | 标注在接口办法上,形容接口的用处 | value=”阐明办法的用处、作用” notes=”办法的备注” |
@ApiImplicitParams | 标注在申请的办法上,代表一组参数(使用于单体参数,不是javabean参数) | value = {@ApiImplicitParam…} |
@ApiImplicitParam | 写在@ApiImplicitParams的value={}中,形容每个参数 | 见附3.1 |
@ApiModel | 标注在javabean参数和响应对象上,形容javabean含意 | value=”形容对象含意” |
@ApiModelProperty | 标注在javabean参数和响应对象属性上,形容属性含意 | name=”参数”,value=”含意”,required=true/false |
附3.1:
- name=”参数”
- value=”参数含意形容”
- required=true/false是否必传
-
paramType=”参数地位”
- header:参数在申请头,通过@RequestHeader获取
- query:参数通过@RequestParam获取
- path:参数在restfull接口url上,通过@PathVariable获取
- dataType=”参数类型,如String等”
- defaultValue=”参数默认值”
举个栗子:
/**
* @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地址扔给她,洒脱转身来到。程序改变也不必从新写一份,改了哪里注解改一下就行了。
4.“你这页面好丑啊”
“你这页面好丑啊,接口多了也不好找。。。。”
“线上调试,接口做了鉴权没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/…
点个赞啊亲
如果你认为本文对你有帮忙,能够「在看/转发/赞/star」,多谢
如果你还发现了更好或不同的想法,还能够在留言区一起探讨下
欢送关注公众号:「其实是白羊」干货继续更新中……
发表回复