SpringBoot 优雅整合Swagger Api 自动生成文档

kenx 等级 458 0 0

前言

一个好的可持续交付的项目,项目说明,和接口文档是必不可少的,swagger api 就可以帮我们很容易自动生成api 文档,不需要单独额外的去写,无侵入式,方便快捷大大减少前后端的沟通方便查找和测试接口提高团队的开发效率方便新人了解项目,剩余的时间就可以去约妹子啦 SpringBoot 优雅整合Swagger 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>

正如官网所说

SpringBoot 优雅整合Swagger Api 自动生成文档

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界面如下:

SpringBoot 优雅整合Swagger Api 自动生成文档 相比较原来界面UI更加漂亮了,信息更完善功能更强大

Swagger常用注解

SpringBoot 优雅整合Swagger Api 自动生成文档

Api标记

用在请求的类上,表示对类的说明,也代表了这个类是swagger2的资源

参数:

  1. tags:说明该类的作用,参数是个数组,可以填多个。
  2. value="该参数没什么意义,在UI界面上不显示,所以不用配置"
  3. description = "用户基本信息操作"

    ApiOperation标记

    用于请求的方法上表示一个http请求的操作

参数:

  1. value用于方法描述
  2. notes用于提示内容
  3. tags可以重新分组(视情况而用)

    ApiParam标记

    用于请求方法上对请求参数,字段说明;表示对参数的添加元数据(说明或是否必填等)

参数:

  1. name–参数名
  2. value–参数说明
  3. required–是否必填

    ApiModel标记

    用于java实体类上表示对类进行说明,用于参数用实体类接收

参数:

  1. value–表示对象名

  2. description–描述 都可省略

    ApiModelProperty标记

    用于方法,字段; 表示对model属性的说明或者数据操作更改

    参数:

  3. value–字段说明

  4. name–重写属性名字

  5. dataType–重写属性类型

  6. required–是否必填

  7. example–举例说明

  8. 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

参数:

  1. name–参数名
  2. value–参数说明
  3. dataType–数据类型
  4. paramType–参数类型
  5. 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(){

  }

总结

  1. 可以给实体类和接口添加注释信息
  2. 接口文档实时更新
  3. 在线测试
  4. kinfe4j 在swagger API只做增强,不会改变原有任何使用,更多增加使用功能 点击这里进入kinfe4j官网文档
收藏
评论区

相关推荐

Vue3.0--Vue Composition API使用体验
本文将之前采用Vue2.6开发的todoList小项目改造成为Vue3.0编写,并介绍一下2.x和3.x之间写法的不同之处。 Vue3.x适配大部分Vue2.x的组件配置,也就是说以前我们在Vue2.x针对组件的一些配置项,例如: export default { name: 'test', components: {}, props: {},
微信支付 (JSSDK支付)
官方文档 微信支付 https://pay.weixin.qq.com/wiki/doc/api/jsapi.php?chapter7_7&index6 微信授权获取code https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/JSSDK.html58 准备工作 微信公
Vue3.0 高频出现的几道面试题
1. Vue 3.0 性能提升主要是通过哪几方面体现的? 1.响应式系统提升 vue2在初始化的时候,对data中的每个属性使用definepropery调用getter和setter使之变为响应式对象。如果属性值为对象,还会递归调用defineproperty使之变为响应式对象。 vue3使用proxy对象重写响应式。proxy的性能本来比def
Vue3.0 所采用的 Composition Api 与 Vue2.x 使用的 Options Api 有什么不同?
开始之前 Composition API 可以说是Vue3最大的特点,那么为什么要推出Composition Api,解决了什么问题? 通常使用Vue2开发
笔趣阁小说api
笔趣阁api小说api,提供小说相关api接口,目前支持笔趣阁(https://m.bqkan.com/)。ip地址:http://49.234.123.245:8082 笔趣阁(https://m.bqkan.com/) 1. 首页 ip/getHome 2. 小说分类 ip/
Fabric1.4:Go 链码开发与编写
1 链码结构 1.1 链码接口 链码启动必须通过调用 shim 包中的 Start 函数,传递一个类型为 Chaincode 的参数,该参数是一个接口类型,有两个重要的函数 Init 与 Invoke 。 type Chainc
初识Windows API
Windows API是什么 Windows系统是一个很大的服务中心,调用这个服务中心的各种服务(每一种服务 ,就是一个函数)可以帮应用程序达到开启视窗、描绘图形、使用周边设备等,由于这些函数服务的对象是应用程序(Applicati
浅谈Vue3新特性
Vue3的已发布一段时间了,新的Vue3在语法以及底层都进行了全新的重构,带来了更快的运行速度,更小的构建包,更友好的编程规范,让我们来看看有哪些变化吧。更快传统的虚拟dom算法:组件patch的时候,需要重新创建整个vdom树,然后遍历整棵树进行diff,update...更快的虚拟dom算法,源自编译模板时给予更多的运行时提示:1. 编译模板时对动
Fetch API 教程
Fetch API 教程作者: 日期: fetch()是 XMLHttpRequest 的升级版,用于在 JavaScript 脚本里面发出 HTTP 请求。浏览器原生提供这个对象。本文详细介绍它的用法。一、基本用法fetch()的功能与 XMLHttpRequest 基本相同,但有三个主要的差异。(1)fetc
Vue3 - 响应性API
前言Vue3.x正式版发布已经快半年了,相信大家也多多少少也用Vue3.x开发过项目。那么,我们今天就整理下Vue3.x中的响应性API。响应性API reactive作用: 创建一个响应式数据。本质: 传入数据(复杂类型:数组和json对象)包装成一个Proxy对象。如果传入其他对象,默认情况下修改对象,界面不会自动更新,如果想更新,可以通过重新赋值(创建
Spring Boot 无侵入式 实现RESTful API接口统一JSON格式返回
前言现在我们做项目基本上中大型项目都是选择前后端分离,前后端分离已经成了一个趋势了,所以总这样·我们就要和前端约定统一的api 接口返回json 格式,这样我们需要封装一个统一通用全局 模版api返回格式,下次再写项目时候直接拿来用就可以了 约定JSON格式一般我们和前端约定json格式是这样的json "code": 200, "message
个人博客开发之技术选型规划
项目技术1. SpringBoot2.4.7 技术栈2. MybatisPlus3.4.x ORM框架3. Mysql8.0 数据库4. IDEA 2021 开发工具5. Mac pro 电脑6. Redis 缓存7. Thymeleaf 模版引擎 项目架构1. 打算用现在最流行的架构模式,前后端分离,采用RESTful API 规范风格json api
SpringBoot 优雅整合Swagger Api 自动生成文档
前言一个好的可持续交付的项目,项目说明,和接口文档是必不可少的,swagger api 就可以帮我们很容易自动生成api 文档,不需要单独额外的去写,无侵入式,方便快捷大大减少前后端的沟通方便查找和测试接口提高团队的开发效率方便新人了解项目,剩余的时间就可以去约妹子啦 整合swagger api这里我们自己去整合swagger api比较麻烦,要导入好几个包
Ory Kratos 用户认证
为用户认证与管理系统。本文将动手实现浏览器(React+AntD)的完整流程,实际了解下它的 API 。 代码: https://github.com/ikuokuo/startorykratos 了解 Kratos 获取代码bashgit clone b v0.7.0alpha.1 depth 1 https://github.com/ory/kratos