目录
swagger是专门开发文档的，API文档(接口文档)，方便前后端工程师信息交互
knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案。
一、Swagger2简介
1、前言
接口文档对于前后端开发人员都十分重要，
尤其近几年流行前后端分离接口文档又变成重中之重，
接口文档固然重要，但是由于项目周期等原因，
后端人员经常出现无法及时更新，导致前端人员抱怨接口文档和实际情况不一致
很多人员会抱怨别人写的接口文档不规范不及时更新，
但是当自己写的时候确实最烦去写这个文档，
这种痛苦只有亲身经历才会牢记于心，
如果接口文档可以实时动态生成，就不会出现上面问题
Swagger可以完美解决上面的问题2、Open API是什么
Open API规范以前叫Swagger规范，是REST API 的API描述格式
Open API文件允许描述整个API，包括：
- 每个访问地址的类型。POST(写->post增,put改,delete删)或GET(读)。
- 每个操作的参数。包括输入输出参数
- 认证方法。
- 连接信息，声明，使用团队和其他信息。
Open API 规范可以使用YAML(树状)或JSON格式进行编写。这样更利于我们和机械进行阅读
Open API规范(OAS)为RUST API定义了一个与语言无关的标准接口，允许人和计算机发现和理解服务的功能，而无需访问源代码，文档或通过网络流量检查。正确定义后，消费者可以使用最少的实现逻辑来理解远程服务并与之交互。
然后，文档生成工具可以使用Open API来定义显示API，使用各种编程语言生成服务器和客户端的代码生成工具，测试工具以及其他用例。
3、Swagger简介
Swagger是一套围绕open的开源工具，可以帮助设计，构建，记录和使用REST API。
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
3.1、特性
1、及时性 (接口变更后，能够及时准确地通知相关前后端开发人员)
2、规范性 (并且保证接口的规范性，如接口的地址，请求方式，参数及响应格式和错误信息)
3、一致性 (接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧)
4、可测性 (直接在接口文档上进行测试，以方便理解业务)
3.2、组件
Swagger Editor：基于浏览器编辑器，可以在里面边写OpenAPI规范，类似Markdown具有实时预览描述文件的功能。(偶然会在配置中出现，通过配置的方式可以实现定制化的文档显示，用的比较少，因为还要程序员自己写)
Swagger UI：将Open API规范呈现为交互式API文档。用可视化UI展示描述文件。(主要用于读，常见，可以将代码中嵌入的Swagger读出来也就是注解)
Swagger Codegen：将Open API规范生成为服务器存根和客户端库。通过Swagger Codegen可以将描述文件生成html格式和cwiki形式的接口文档，同时也可以生成多种言语的客户端和服务端代码。
Swagger Inspector：和Swagger UI有点类似，但是可以返回更多信息，也会保存请求的实际参数数据。(类似ui加了过程记录)
Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。
使用Swagger，就是把相关的信息存储在它定义的描述文件里面(yml或json格式)，再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。
二、knife4j
文档地址：Knife4j · 集Swagger2及OpenAPI3为一体的增强解决方案. | Knife4j
knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案。
knife4j属于service模块公共资源，因此我们集成到service-uitl模块
三、内容
3.1、依赖
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
</dependency>3.2、配置类
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;
import java.util.ArrayList;
import java.util.List;
/**
* @author
* @Description swagger2配置类
* @date
*/
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig {
@Bean
public Docket adminApiConfig(){
List<Parameter> pars = new ArrayList<>();
ParameterBuilder tokenPar = new ParameterBuilder();
tokenPar.name("token")
.description("用户token")
.defaultValue("")
.modelRef(new ModelRef("string"))
.parameterType("header")
.required(false)
.build();
pars.add(tokenPar.build());
//添加head参数end
Docket adminApi = new Docket(DocumentationType.SWAGGER_2)
.groupName("adminApi")
.apiInfo(adminApiInfo())
.select()
//只显示admin路径下的页面
.apis(RequestHandlerSelectors.basePackage("com.xx"))
.paths(PathSelectors.regex("/admin/.*"))
.build()
.globalOperationParameters(pars);
return adminApi;
}
private ApiInfo adminApiInfo(){
return new ApiInfoBuilder()
.title("后台管理系统-API文档")
.description("本文档描述了后台管理系统微服务接口定义")
.version("1.0")
.contact(new Contact("xx", "http://xx.com", "xx@qq.com"))
.build();
}
}
3.3、Controller层添加注解
package com.lhw.controller;
import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.lhw.exception.lhwException;
import com.lhw.model.system.SysRole;
import com.lhw.model.vo.SysRoleQueryVo;
import com.lhw.result.Result;
import com.lhw.service.SysRoleService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import org.yaml.snakeyaml.events.Event;
import java.util.List;
/**
* @author xx
* @Description
* @date
*/
@Api(tags = "角色管理接口")
@RestController
@RequestMapping("/admin/system/sysRole")
public class SysRoleController {
/**
* http://localhost:8800/doc.html
*/
@Autowired
private SysRoleService sysRoleService;
/**
* 批量新增
* @param sysRoleList
* @RequestBody(json中的数组格式 -》 java中的list集合)
* @return
*/
@ApiOperation("批量新增角色接口")
@PostMapping("saveBatch")
public Result saveBatch(@RequestBody List<SysRole> sysRoleList){
boolean isSuccess = sysRoleService.saveBatch(sysRoleList);
if (isSuccess){
return Result.ok();
}
else {
return Result.fail();
}
}
}
3.4、实体类层添加注解
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableName;
import com.lhw.model.base.BaseEntity;
import io.swagger.annotations.ApiModelProperty;
import lombok.Builder;
import lombok.Data;
@Data
@Builder
@TableName("sys_role")
public class SysRole extends BaseEntity {
private static final long serialVersionUID = 1L;
@ApiModelProperty(value = "角色名称")
@TableField("role_name")
private String roleName;
@ApiModelProperty(value = "角色编码")
@TableField("role_code")
private String roleCode;
@ApiModelProperty(value = "角色描述")
@TableField("description")
private String description;
}3.4、测试
测试地址http://localhost:8800/doc.html
4581
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
