一篇学会Swagger2(集成knife4j)

目录

一、Swagger2简介

1、前言

2、Open API是什么

3、Swagger简介

3.1、特性

3.2、组件

二、knife4j

三、内容

3.1、依赖

3.2、配置类

3.3、Controller层添加注解

3.4、测试


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

  • 0
    点赞
  • 0
    收藏
    觉得还不错? 一键收藏
  • 打赏
    打赏
  • 0
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

键可不冷

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值