前言
一个好的可继续交付的我的项目，我的项目阐明，和接口文档是必不可少的，swagger api 就能够帮咱们很容易主动生成api 文档，不须要独自额定的去写，无侵入式，方便快捷大大减少前后端的沟通不便查找和测试接口进步团队的开发效率不便新人理解我的项目，残余的工夫就能够去约妹子啦
整合swagger api
这里咱们本人去整合swagger api比拟麻烦，要导入好几个包，有大神帮咱们写好了轮子kinfe4j间接对应SpringBoot的启动项，而且在不影响原来应用性能上界面ui做了丑化性能做了加强 咱们间接整合这个就好了
<!--api 文档-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.1</version>
</dependency>正如官网所说
kinfe4j官网文档点击这里
自定义配置信息
为咱们为swagger配置更多的接口阐明
package cn.soboys.core.config;
import cn.hutool.core.collection.CollUtil;
import cn.soboys.core.ret.ResultCode;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Response;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import javax.annotation.Resource;
import java.util.Arrays;
import java.util.List;
/**
* @author kenx
* @version 1.0
* @date 2021/6/21 16:02
* api 配置类
*/
@Configuration
public class SwaggerConfigure {
@Resource
private SwaggerProperty swaggerProperty;
/**
* 结构api 文档
* @return
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30).globalResponses(HttpMethod.POST, this.responseList()) //全局respons信息
.apiInfo(apiInfo(swaggerProperty)) //文档信息
.select()
//文档扫描
//.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //有ApiOperation注解的controller都退出api文档
.apis(RequestHandlerSelectors.basePackage(swaggerProperty.getBasePackage())) //包模式
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo(SwaggerProperty swagger) {
return new ApiInfoBuilder()
//题目
.title(swagger.getTitle())
//形容
.description(swagger.getDescription())
//创立联系人信息 （作者，邮箱，网站）
.contact(new Contact(swagger.getAuthor(), swagger.getUrl(), swagger.getEmail()))
//版本
.version(swagger.getVersion())
//认证
.license(swagger.getLicense())
//认证协定
.licenseUrl(swagger.getLicenseUrl())
.build();
}
/**
* 全局response 返回信息
* @return
*/
private List<Response> responseList() {
List<Response> responseList = CollUtil.newArrayList();
Arrays.stream(ResultCode.values()).forEach(errorEnum -> {
responseList.add(
new ResponseBuilder().code(errorEnum.getCode().toString()).description(errorEnum.getMessage()).build()
);
});
return responseList;
}
}
抽出api文档配置模版信息为属性文件不便复用
package cn.soboys.core.config;
import lombok.Data;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.SpringBootConfiguration;
/**
* @author kenx
* @version 1.0
* @date 2021/6/21 16:01
* api 文档信息
*/
@Data
@SpringBootConfiguration
public class SwaggerProperty {
/**
* 须要生成api文档的 类
*/
@Value("${swagger.basePackage}")
private String basePackage;
/**
* api文档 题目
*/
@Value("${swagger.title}")
private String title;
/**
* api文档 形容
*/
@Value("${swagger.description}")
private String description;
/**
* api文档 版本
*/
@Value("${swagger.version}")
private String version;
/**
* api 文档作者
*/
@Value("${swagger.author}")
private String author;
/**
* api 文档作者网站
*/
@Value("${swagger.url}")
private String url;
/**
* api文档作者邮箱
*/
@Value("${swagger.email}")
private String email;
/**
* api 文档 认证协定
*/
@Value("${swagger.license}")
private String license;
/**
* api 文档 认证 地址
*/
@Value("${swagger.licenseUrl}")
private String licenseUrl;
}简略应用
在你的Controller上增加swagger注解
@Slf4j
@Api(tags = "登录")
public class LoginController {
private final IUsersService userService;
@PostMapping("/login")
@ApiOperation("用户登录")
public String login(@RequestBody UserLoginParams userLoginParams) {
Users u = userService.login(userLoginParams);
return "ok";
}
}留神如启用了拜访权限，还需将swagger相干uri容许匿名拜访
/swagger**/**
/webjars/**
/v3/**
/doc.html重启服务，自带api文档拜访链接为/doc.html界面如下:
相比拟原来界面UI更加丑陋了，信息更欠缺性能更弱小
## Swagger罕用注解
Api标记
用在申请的类上，示意对类的阐明，也代表了这个类是swagger2的资源
参数：
- tags：阐明该类的作用，参数是个数组，能够填多个。
- value=”该参数没什么意义，在UI界面上不显示，所以不必配置”
-
description = “用户根本信息操作”
ApiOperation标记
用于申请的办法上示意一个http申请的操作
参数:
- value用于办法形容
- notes用于提醒内容
-
tags能够从新分组（视状况而用）
ApiParam标记
用于申请办法上对申请参数，字段阐明；示意对参数的增加元数据（阐明或是否必填等）
参数：
- name–参数名
- value–参数阐明
-
required–是否必填
ApiModel标记
用于java实体类上示意对类进行阐明，用于参数用实体类接管
参数：
- value–示意对象名
-
description–形容
都可省略
### ApiModelProperty标记
用于办法，字段； 示意对model属性的阐明或者数据操作更改参数：
- value–字段阐明
- name–重写属性名字
- dataType–重写属性类型
- required–是否必填
- example–举例说明
- hidden–暗藏
@ApiModel(value="user对象",description="用户对象user")
public class User implements Serializable{
private static final long serialVersionUID = 1L;
@ApiModelProperty(value="用户名",name="username",example="xingguo")
private String username;
@ApiModelProperty(value="状态",name="state",required=true)
private Integer state;
private String password;
private String nickName;
private Integer isDeleted;
@ApiModelProperty(value="id数组",hidden=true)
private String[] ids;
private List<String> idList;
//省略get/set
}ApiIgnore标记
用于申请类或者办法上，能够不被swagger显示在页面上
ApiImplicitParam标记
用于办法示意独自的申请参数
ApiImplicitParams标记
用于办法，蕴含多个 @ApiImplicitParam
参数：
- name–参数名
- value–参数阐明
- dataType–数据类型
- paramType–参数类型
- example–举例说明
@ApiOperation("查问测试")
@GetMapping("select")
//@ApiImplicitParam(name="name",value="用户名",dataType="String", paramType = "query")
@ApiImplicitParams({
@ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="xingguo"),
@ApiImplicitParam(name="id",value="用户id",dataType="long", paramType = "query")})
public void select(){
}总结
- 能够给实体类和接口增加正文信息
- 接口文档实时更新
- 在线测试
- kinfe4j 在swagger API只做加强，不会扭转原有任何应用，更多减少应用性能
点击这里进入kinfe4j官网文档
发表回复