SpringBoot第16讲:如何生成接口文档之Swagger技术栈

news2024/9/21 18:10:11

SpringBoot第16讲:如何生成接口文档之Swagger技术栈

SpringBoot开发Restful接口,有什么API规范吗?如何快速生成API文档呢?Swagger 是一个用于生成、描述和调用 RESTful 接口的 Web 服务。通俗的来讲,Swagger 就是将项目中所有(想要暴露的)接口展现在页面上,并且可以进行接口调用和测试的服务。本文是SpringBoot第16讲,主要介绍OpenAPI规范,以及Swagger技术栈基于OpenAPI规范的集成方案。

文章目录

  • SpringBoot第16讲:如何生成接口文档之Swagger技术栈
    • 1、准备知识点
      • 1.1、什么是OpenAPI规范(OAS)?
      • 1.2、什么是Swagger?
      • 1.3、Swagger和SpringFox有啥关系?
      • 1.4、什么是Knife4J? 和Swagger什么关系?
    • 2、实现案例之Swagger3
      • 2.1、POM
      • 2.2、Swagger Config
      • 2.3、controller 接口
      • 2.4、运行测试
    • 3、实现案例之Knife4J
      • 3.1、POM
      • 3.2、yml配置
      • 3.3、注入配置
      • 3.4、Controller接口
      • 3.5、运行测试
    • 4、示例源码
    • 5、白龙马对Swagger的使用

1、准备知识点

在生成文档前,你需要了解下OpenAPI规范,Swagger,SpringFox,Knife4J,Swagger UI等之间的关系。

1.1、什么是OpenAPI规范(OAS)?

OpenAPI 规范(OAS)定义了一个标准的、语言无关的 RESTful API 接口规范,它可以同时允许开发人员和操作系统查看并理解某个服务的功能,而无需访问源代码,文档或网络流量检查(既方便人类学习和阅读,也方便机器阅读)。正确定义 OAS 后,开发者可以使用最少的实现逻辑来理解远程服务并与之交互

此外,文档生成工具可以使用 OpenAPI 规范来生成 API 文档,代码生成工具可以生成各种编程语言下的服务端和客户端代码,测试代码和其他用例。

官方GitHub地址: OpenAPI-Specification

1.2、什么是Swagger?

Swagger 是一个用于生成、描述和调用 RESTful 接口的 Web 服务。通俗的来讲,Swagger 就是将项目中所有(想要暴露的)接口展现在页面上,并且可以进行接口调用和测试的服务。

从上述 Swagger 定义我们不难看出 Swagger 有以下 3 个重要的作用:

  • 将项目中所有的接口展现在页面上,这样后端程序员就不需要专门为前端使用者编写专门的接口文档;
  • 当接口更新之后,只需要修改代码中的 Swagger 描述就可以实时生成新的接口文档了,从而规避了接口文档老旧不能使用的问题;
  • 通过 Swagger 页面,我们可以直接进行接口调用,降低了项目开发阶段的调试成本

Swagger3完全遵循了 OpenAPI 规范。Swagger 官网地址:https://swagger.io/。

1.3、Swagger和SpringFox有啥关系?

Swagger 可以看作是一个遵循了 OpenAPI 规范的一项技术,而 springfox 则是这项技术的具体实现。 就好比 Spring 中的 IOC 和 DI 的关系 一样,前者是思想,而后者是实现。

1.4、什么是Knife4J? 和Swagger什么关系?

本质是Swagger的增强解决方案,前身只是一个SwaggerUI(swagger-bootstrap-ui)

Knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍!

Knife4j的前身是swagger-bootstrap-ui,为了契合微服务的架构发展,由于原来swagger-bootstrap-ui采用的是后端Java代码+前端Ui混合打包的方式,在微服务架构下显的很臃肿,因此项目正式更名为knife4j

更名后主要专注的方面

  • 前后端Java代码以及前端Ui模块进行分离,在微服务架构下使用更加灵活
  • 提供专注于Swagger的增强解决方案,不同于只是改善增强前端Ui部分

相关文档请参考:https://doc.xiaominfo.com/knife4j/documentation/

2、实现案例之Swagger3

我们先看下最新Swagger3 如何配置和实现接口。

2.1、POM

根据上文介绍,我们引入springfox依赖包,最新的是3.x.x版本。和之前的版本比,只需要引入如下的starter包即可。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2.2、Swagger Config

我们在配置中还增加了一些全局的配置,比如全局参数等

package springboot.swagger.config;

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import springfox.documentation.builders.*;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.schema.ScalarType;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springboot.swagger.constant.ResponseStatus;
import java.util.ArrayList;
import java.util.List;
import java.util.stream.Collectors;

/**
 * swagger config for open api.
 *
 * @author qiwenjie
 */
@Configuration
@EnableOpenApi
public class SwaggerConfig {

    /**
     * @return swagger config
     */
    @Bean
    public Docket openApi() {
        return new Docket(DocumentationType.OAS_30)
                .groupName("Test group")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build()
                .globalRequestParameters(getGlobalRequestParameters())
                .globalResponses(HttpMethod.GET, getGlobalResponse());
    }

    /**
     * @return global response code->description
     */
    private List<Response> getGlobalResponse() {
        return ResponseStatus.HTTP_STATUS_ALL.stream().map(
                a -> new ResponseBuilder().code(a.getResponseCode()).description(a.getDescription()).build())
                .collect(Collectors.toList());
    }

    /**
     * @return global request parameters
     */
    private List<RequestParameter> getGlobalRequestParameters() {
        List<RequestParameter> parameters = new ArrayList<>();
        parameters.add(new RequestParameterBuilder()
                .name("AppKey")
                .description("App Key")
                .required(false)
                .in(ParameterType.QUERY)
                .query(q -> q.model(m -> m.scalarModel(ScalarType.STRING)))
                .required(false)
                .build());
        return parameters;
    }

    /**
     * @return api info
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger API")
                .description("test api")
                .contact(new Contact("qiwenjie", "https://blog.csdn.net/qq_28959087", "1172814226@qq.com"))
                .termsOfServiceUrl("http://xxxxxx.com/")
                .version("1.0")
                .build();
    }
}

2.3、controller 接口

package springboot.swagger.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import springboot.swagger.entity.param.UserParam;
import springboot.swagger.entity.vo.AddressVo;
import springboot.swagger.entity.vo.UserVo;
import java.util.Collections;
import java.util.List;

/**
 * @author qiwenjie
 */
@Api
@RestController
@RequestMapping("/user")
public class UserController {

    /**
     * http://localhost:8080/user/add .
     *
     * @param userParam user param
     * @return user
     */
    @ApiOperation("Add User")
    @PostMapping("add")
    @ApiImplicitParam(name = "userParam", type = "body", dataTypeClass = UserParam.class, required = true)
    public ResponseEntity<String> add(@RequestBody UserParam userParam) {
        return ResponseEntity.ok("success");
    }

    /**
     * http://localhost:8080/user/list .
     *
     * @return user list
     */
    @ApiOperation("Query User List")
    @GetMapping("list")
    public ResponseEntity<List<UserVo>> list() {
        List<UserVo> userVoList = Collections.singletonList(UserVo.builder().name("dai").age(18)
                .address(AddressVo.builder().city("SZ").zipcode("10001").build()).build());
        return ResponseEntity.ok(userVoList);
    }
}

2.4、运行测试

打开文档API网页

img

测试添加一个用户

img

查询用户列表

img

3、实现案例之Knife4J

这里展示目前使用Java生成接口文档的最佳实践: SwaggerV3(OpenAPI)+ Knife4J。

3.1、POM

<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-spring-boot-starter -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

3.2、yml配置

server:
  port: 8080
knife4j:
  enable: true
  documents:
    - group: Test Group
      name: My Documents
      locations: classpath:wiki/*
  setting:
    # default lang
    language: en-US
    # footer
    enableFooter: false
    enableFooterCustom: true
    footerCustomContent: MIT
    # header
    enableHomeCustom: true
    homeCustomLocation: classpath:wiki/README.md
    # models
    enableSwaggerModels: true
    swaggerModelName: My Models

3.3、注入配置

package springboot.knife4j.config;

import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import springboot.knife4j.constant.ResponseStatus;
import springfox.documentation.builders.*;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.schema.ScalarType;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import java.util.ArrayList;
import java.util.List;
import java.util.stream.Collectors;

/**
 * swagger config for open api.
 *
 * @author qiwenjie
 */
@Configuration
@EnableOpenApi
public class OpenApiConfig {

    /**
     * open api extension by knife4j.
     */
    private final OpenApiExtensionResolver openApiExtensionResolver;

    @Autowired
    public OpenApiConfig(OpenApiExtensionResolver openApiExtensionResolver) {
        this.openApiExtensionResolver = openApiExtensionResolver;
    }

    /**
     * @return swagger config
     */
    @Bean
    public Docket openApi() {
        String groupName = "Test Group";
        return new Docket(DocumentationType.OAS_30)
                .groupName(groupName)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build()
                .globalRequestParameters(getGlobalRequestParameters())
                .globalResponses(HttpMethod.GET, getGlobalResponse())
                .extensions(openApiExtensionResolver.buildExtensions(groupName))
                .extensions(openApiExtensionResolver.buildSettingExtensions());
    }

    /**
     * @return global response code->description
     */
    private List<Response> getGlobalResponse() {
        return ResponseStatus.HTTP_STATUS_ALL.stream().map(
                a -> new ResponseBuilder().code(a.getResponseCode()).description(a.getDescription()).build())
                .collect(Collectors.toList());
    }

    /**
     * @return global request parameters
     */
    private List<RequestParameter> getGlobalRequestParameters() {
        List<RequestParameter> parameters = new ArrayList<>();
        parameters.add(new RequestParameterBuilder()
                .name("AppKey")
                .description("App Key")
                .required(false)
                .in(ParameterType.QUERY)
                .query(q -> q.model(m -> m.scalarModel(ScalarType.STRING)))
                .required(false)
                .build());
        return parameters;
    }

    /**
     * @return api info
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("My API")
                .description("test api")
                .contact(new Contact("qiwenjie", "https://blog.csdn.net/qq_28959087", "1172814226@qq.com"))
                .termsOfServiceUrl("http://xxxxxx.com/")
                .version("1.0")
                .build();
    }
}

其中ResponseStatus封装

import lombok.AllArgsConstructor;
import lombok.Getter;

import java.util.Arrays;
import java.util.Collections;
import java.util.List;

@Getter
@AllArgsConstructor
public enum ResponseStatus {

    SUCCESS("200", "success"),
    FAIL("500", "failed"),

    HTTP_STATUS_200("200", "ok"),
    HTTP_STATUS_400("400", "request error"),
    HTTP_STATUS_401("401", "no authentication"),
    HTTP_STATUS_403("403", "no authorities"),
    HTTP_STATUS_500("500", "server error");

    public static final List<ResponseStatus> HTTP_STATUS_ALL = Collections.unmodifiableList(
            Arrays.asList(HTTP_STATUS_200, HTTP_STATUS_400, HTTP_STATUS_401, HTTP_STATUS_403, HTTP_STATUS_500
            ));

    /**
     * response code
     */
    private final String responseCode;

    /**
     * description.
     */
    private final String description;

}

3.4、Controller接口

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import tech.pdai.springboot.knife4j.entity.param.AddressParam;

/**
 * Address controller test demo.
 */
@Api(value = "Address Interfaces", tags = "Address Interfaces")
@RestController
@RequestMapping("/address")
public class AddressController {
    /**
     * http://localhost:8080/address/add .
     *
     * @param addressParam param
     * @return address
     */
    @ApiOperation("Add Address")
    @PostMapping("add")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "city", type = "query", dataTypeClass = String.class, required = true),
            @ApiImplicitParam(name = "zipcode", type = "query", dataTypeClass = String.class, required = true)
    })
    public ResponseEntity<String> add(AddressParam addressParam) {
        return ResponseEntity.ok("success");
    }

}

3.5、运行测试

自定义用户主页 http://localhost:8080/doc.html#/home

在这里插入图片描述

model模型

在这里插入图片描述

全局参数 和配置

在这里插入图片描述

自定义文档

-

接口文档和测试接口

在这里插入图片描述

4、示例源码

其它旧版本的实现:

  • swagger2
  • Swagger2+BootstrapUI
  • Knife4j v2

Todo

5、白龙马对Swagger的使用

todo

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.coloradmin.cn/o/834778.html

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈,一经查实,立即删除!

相关文章

FANUC机器人SRVO-300机械手断裂故障报警原因分析及处理办法

FANUC机器人SRVO-300机械手断裂故障报警原因分析及处理办法 首先,我们查看报警说明书上的介绍: 总结:即在机械手断裂设置为无效时,机器人检测出了机械手断裂信号(不该有的信号,现在检测到了,所以报警) 使机械手断裂设定为无效/有效的具体方法:  按下示教器的MENU菜单…

springboot()—— swagger

零、一张图读懂swagger 懂了&#xff0c;这玩意就是用swagger搞出来的&#xff01; 就是一个后端开发自测的东西嘛&#xff01; 一、概念 存在即合理&#xff0c;我们看一下swagger诞生的原因&#xff1a;在前后端分离的架构中&#xff0c;前端新增一个字段&#xff0c;后端就…

【Java数据结构】第七章 —— 栈

目录 一、栈 二、栈的主要方法 三、栈的模拟实现 3.1 构造方法和成员属性 3.2 push 方法 3.3 pop 方法 3.4 peek 方法 3.5 size 方法 一、栈 <

工程监测仪器多通道振弦数据记录仪的MODBUS通讯协议解析

工程监测仪器多通道振弦数据记录仪的MODBUS通讯协议解析 多通道振弦数据记录仪是多通道振弦、温度信号采集记录仪&#xff0c; 具备 32 通道传感器接口&#xff0c; 可对最多16 通道振弦频率和 16 通道温度、 32 通道振弦频率进行实时或全自动定时采集记录&#xff08;支持内部…

【C++奇遇记】函数探幽(上)

&#x1f3ac; 博客主页&#xff1a;博主链接 &#x1f3a5; 本文由 M malloc 原创&#xff0c;首发于 CSDN&#x1f649; &#x1f384; 学习专栏推荐&#xff1a;LeetCode刷题集 数据库专栏 初阶数据结构 &#x1f3c5; 欢迎点赞 &#x1f44d; 收藏 ⭐留言 &#x1f4dd; 如…

操作系统 - 小记 230803

文章目录 计算机的硬件组成程序的存储和执行程序语言的设计和进化存储设备的层次结构操作系统 https://www.bilibili.com/video/BV1Q5411w7z5?p2 计算机的硬件组成 CPU CU&#xff0c;控制单元ALU&#xff0c;算数逻辑单元寄存器 IO Bridge 处理器和外部交互的桥梁Main Memory…

redis原理 4:雷厉风行 —— 管道

大多数同学一直以来对 Redis 管道有一个误解&#xff0c;他们以为这是 Redis 服务器提供的一种特别的技术&#xff0c;有了这种技术就可以加速 Redis 的存取效率。但是实际上 Redis 管道 (Pipeline) 本身并不是 Redis 服务器直接提供的技术&#xff0c;这个技术本质上是由客户端…

【LeetCode-简单】剑指 Offer 22. 链表中倒数第k个节点(详解)

题目 输入一个链表&#xff0c;输出该链表中倒数第k个节点。为了符合大多数人的习惯&#xff0c;本题从1开始计数&#xff0c;即链表的尾节点是倒数第1个节点。 例如&#xff0c;一个链表有 6 个节点&#xff0c;从头节点开始&#xff0c;它们的值依次是 1、2、3、4、5、6。这…

2024年杭电MBA项目招生信息全面了解

2024年全国管理类硕士联考备考已经到了最火热的阶段&#xff0c;不少考生开始持续将注意力集中在备考的规划中&#xff01;杭州达立易考教育整合浙江省内的MBA项目信息&#xff0c;为大家详细梳理了相关报考参考内容&#xff0c;方便大家更好完成择校以及针对性的备考工作。本期…

差异对比犀利手册:使用 Partial Diff 插件在 VSCode 中比较代码差异

简介&#xff1a; 在本教程中&#xff0c;我们将介绍如何在 Visual Studio Code&#xff08;VSCode&#xff09;编辑器中安装和使用 Partial Diff 插件来进行源代码文件的差异比较。Partial Diff 插件是一个强大且简单的工具&#xff0c;可以帮助你更容易地查看和理解代码的变…

14.2.2 【Linux】software, hardware RAID

磁盘阵列分为硬件与软件。所谓的硬件磁盘阵列是通过磁盘阵列卡来达成阵列的目的。磁盘阵列卡上面有一块专门的芯片在处理 RAID 的任务&#xff0c;因此在性能方面会比较好。在很多任务 &#xff08;例如 RAID 5 的同位检查码计算&#xff09; 磁盘阵列并不会重复消耗原本系统的…

“已停止访问该网页“ 解决流程,微信外部链接内容管理规范

登录手机管家官网 腾讯安全-网址安全中心 自行处理。 说明&#xff1a; 一直以来&#xff0c;微信致力于为用户提供绿色、健康的网络生态环境。 根据法律法规的规定&#xff0c;微信将落实“以安全为底线”的互联互通&#xff0c;为确保高质量的平台内容和良好的用户体验&a…

Multimodal Learning with Transformer: A Survey

Transformer多模态学习 Abstract1 INTRODUCTION2 BACKGROUND2.1 Multimodal Learning (MML)2.2 Transformers: a Brief History and Milestones2.3 Multimodal Big Data 3 TRANSFORMERS: A GEOMETRICALLY TOPOLOGICAL PERSPECTIVE3.1 Vanilla Transformer3.1.1 Input Tokenizat…

使用手机相机检测电脑屏幕刷新率Hz

使用手机相机检测电脑屏幕刷新率Hz 1、电脑打开https://www.testufo.com/frameskipping 2、相机专业模式&#xff1a;快门1/10、ISO自动&#xff0c;拍摄一张照片。120Hz至少要有12个亮块&#xff0c;50Hz至少有6个亮块。 更改刷新速率 1、选择 “开始>设置>系统>显示…

ARM64 常见汇编指令学习 10 -- 无符号位域提取指令 BFXIL

文章目录 BFXIL使用例子 BFXIL 有2种语法&#xff1a; BFXIL Wd, Wn, #lsb, #width ; 32-bit BFXIL Xd, Xn, #lsb, #width ; 64-bit从Wn 寄存器的第 lsb 位开始&#xff0c;提取 width 位&#xff0c;替换 Wd 寄存器的最低 width位&#xff0c;剩余高位不改变。 使用例子 假…

科技云报道:向量数据库:AI时代的下一个热点

科技云报道原创。 最近&#xff0c;又一个概念火了——向量数据库。 随着大模型带来的应用需求提升&#xff0c;4月以来多家海外知名向量数据库创业企业传出融资喜讯。 4月28日&#xff0c;向量数据库平台Pinecone宣布获得1亿美元&#xff08;约7亿元&#xff09;B轮融资&am…

DBeaver连MySQL库报错public key retrieval is not allowed

连接报错: public key retrieval is not allowed解决办法&#xff1a; 右击你连接的库进行编辑连接&#xff08;或者直接按F4打开编辑&#xff09; 然后点击驱动属性里面进行设置 找到allowPublicKeyRetrieval属性&#xff0c;把值由false改为true 注&#xff1a;连接成功后如…

Flutter 混合架构方案探索

得益于 Flutter 优秀的跨平台表现&#xff0c;混合开发在如今的 App 中随处可见&#xff0c;如最近微信公布的小程序新渲染引擎 Skyline 发布正式版也在底层渲染上使用了 Flutter&#xff0c;号称渲染速度提升50%。 在现有的原生 App 中引入 Flutter 来开发不是一件简单的事&a…

Kubernetes高可用集群二进制部署(四)部署kubectl和kube-controller-manager、kube-scheduler

Kubernetes概述 使用kubeadm快速部署一个k8s集群 Kubernetes高可用集群二进制部署&#xff08;一&#xff09;主机准备和负载均衡器安装 Kubernetes高可用集群二进制部署&#xff08;二&#xff09;ETCD集群部署 Kubernetes高可用集群二进制部署&#xff08;三&#xff09;部署…

解密爬虫ip是如何被识别屏蔽的

在当今信息化的时代&#xff0c;网络爬虫已经成为许多企业、学术机构和个人不可或缺的工具。然而&#xff0c;随着网站安全防护的升级&#xff0c;爬虫ip往往容易被识别并屏蔽&#xff0c;给爬虫工作增加了许多困扰。在这里&#xff0c;作为一家专业的爬虫ip供应商&#xff0c;…