Spring Boot 集成 Swagger2构建 API文档

目录
  • 一、Swagger是什么
    • 1.SwaggerEditor
    • 2.SwaggerUI
    • 3.SwaggerCodegen
    • 4.SwaggerUI
  • 二、SpringBoot集成Swagger
    • 1.创建SpringBoot项目
    • 2.引入依赖
    • 3.构建Swagger配置类
    • 4.编写接口
    • 5.查看并测试接口

前言:

不管你是从事前端还是后端开发,相信都难免被接口文档折磨过。如果你是一个前端开发者,可能你会经常发现后端给的接口文档跟实际代码有所出入。而假设你是一个后端开发者,你可能又会觉得自己开发后端接口已经够烦的了,还要花费大量精力去编写和维护接口文档,所以难免有时候会更新不及时。这就可能造成了前后端相互不理解,最后甚至吵起来,哈哈哈 。

这时候我们就会想,有没有一款工具,能让我们快速实现编写接口文档。这个工具既能保证我们的接口文档实时更新,也能保证我们不用花过多时间去维护,就像写注释那么简单。

既然这是大多数前后端程序员的一大痛点,那必须得有一个解决方案吧。而这个方案使用的人多了,慢慢就成了一种规范,大家都默认使用这个方案,从而解决前后端接口文档不同步的问题,而这就是我们今天的主角 - Swagger 的由来。

通过使用 Swagger,我们只需要按照它所给定的一系列规范去定义接口以及接口的相关信息,然后它就能帮我们自动生成各种格式的接口文档,方便前后端开发者进行前后端联调。同时,如果我们的代码接口有所变动,只需要更新 Swagger 的描述,它就能进行实时更新,做到实际代码和接口文档的一致性。

一、Swagger 是什么

Swagger 是一种接口描述语言,主要用于生成、描述、调用以及可视化 RESTful 风格的 Web 服务接口文档。以前的项目可能更多的是前后端未分开同时进行开发,所以接口文档可能不是那么重要。但现在主流的项目基本都是前后端分离,如果前后端没有沟通好,就有可能导致接口文档更新不及时,造成一些不必要的麻烦。而通俗地讲,Swagger 就是帮我们写接口文档的。它不仅能自动生成实时接口文档,还能生成测试用例,方便我们进行测试。

Swagger 主要提供了如下几种开源工具:

1.Swagger Editor

Swagger 所提供的的编辑器,主要用于编辑 Swagger 描述文件,支持实时预览描述文件更新后的效果,类似于我们的 Markdown 编辑器,左边编写源码,右边就可以进行实时预览。该编辑器不仅提供在线使用,还支持本地部署。

2.Swagger UI

提供可视化的 UI 页面,用于展示 Swagger 的描述文件。接口的调用方、测试等都可以通过该页面查阅接口的相关信息,并且进行简单的接口请求测试。

3.Swagger Codegen

通过使用该工具,可以将 Swagger 的描述文件生成 HTML 和 CWIKI 形式的接口文档,而且还能生成针对多种不同语言的服务端和客户端的代码。

4.Swagger UI

平时和我们打交道最多的,可能就是 Swagger UI 这个工具了,它主要用于显示接口文档。根据我们代码中按照 Swagger 规范所设置的描述,自动生成接口说明文档。一个简单的示例如下:

二、Spring Boot 集成 Swagger

1.创建 Spring Boot 项目

通过以上对 Swagger 简单的介绍之后,我们来看看如何在 Spring Boot 项目中使用 Swagger。

首先需要创建一个简单的 Spring Boot 项目,如果你还不知道如何创建,

创建好之后的项目接口如下:

2.引入依赖

创建好Spring Boot 项目之后,需要配置项目 pom.xml 文件,在其中引入 Swagger 的相关依赖。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

3.构建 Swagger 配置类

引入依赖后,接下来就是构建 Swagger 的配置类了。

package com.cunyu.springbootswaggerdemo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

/**
 * Created with IntelliJ IDEA.
 *
 * @author : 村雨遥
 * @version : 1.0
 * @project : springboot-swagger-demo
 * @package : com.cunyu.springbootswaggerdemo.config
 * @className : Swagger2Configuration
 * @createTime : 2022/1/5 22:21
 * @email : 747731461@qq.com
 * @微信 : cunyu1024
 * @公众号 : 村雨遥
 * @网站 : https://cunyu1943.github.io
 * @description :
 */
@Configuration
@EnableSwagger2
public class Swagger2Configuration {

    /**
     * 配置 Swagger 2
     * 注册一个 Bean 属性
     * enable():是否启用 Swagger,启用后才能在浏览器中进行访问
     * groupName():用于配置 API 文档的分组
     */
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(true)
                .groupName("v1")
                .select()
                // 过滤路径
                //.paths(PathSelectors.ant())
                // 指定扫描的包
                .apis(RequestHandlerSelectors.basePackage("com.cunyu.springbootswaggerdemo.controller"))
                .build();
    }

    private ApiInfo apiInfo() {
        /*作者信息*/
        Contact contact = new Contact("村雨遥", "https://cunyu1943.github.io", "747731461@qq.com");
        return new ApiInfo(
                "Swagger 测试接口文档",
                "Spring Boot 集成 Swagger 测试接口文档",
                "v1.0",
                "https://cunyu1943.github.io",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

4.编写接口

配置好 Swagger 后,在我们的项目中添加一个简单的接口,这里以一个简单的有参和无参接口为例。

package com.cunyu.springbootswaggerdemo.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * Created with IntelliJ IDEA.
 *
 * @author : 村雨遥
 * @version : 1.0
 * @project : springboot-swagger-demo
 * @package : com.cunyu.springbootswaggerdemo.controller
 * @className : SwaggerDemoController
 * @createTime : 2022/1/5 22:21
 * @email : 747731461@qq.com
 * @微信 : cunyu1024
 * @公众号 : 村雨遥
 * @网站 : https://cunyu1943.github.io
 * @description :
 */

@Api
@RestController
public class SwaggerDemoController {
    @ApiOperation(value = "hello world 接口")
    @GetMapping("hello")
    public String hello() {
        return "hello world";
    }

    @ApiOperation(value = "有参接口")
    @PostMapping("demo")
    public String demo(@ApiParam(name = "name", value = "村雨遥", required = true) String name) {
        return "hello," + name;
    }
}

5.查看并测试接口

完成上述步骤后,我们启动项目,然后在浏览器中访问如下地址,就可以访问我们项目的接口文档了。

http://localhost:8080/swagger-ui.html

访问如上地址后,如果出现下面的界面,说明我们 Spring Boot 集成 Swagger2 就到此成功了。

点开具体的接口,就会有这个接口的一些详细信息,如下图所示,一般包括:

  • 接口请求方式
  • 接口请求路径及描述
  • 接口请求参数
  • 接口响应

如果我们要进行简单的测试,则点击上图中右上方的 Try it out,然后我们就可以编辑请求参数的值,编辑完成之后点击下方的 Execute 即可查看接口返回值。

以我给的接口为例,我传入了一个参数 name,然后执行 demo 接口,最后会给我返回 hello,name 的结果,其中 name 是我传入的参数值,这里我传入了村雨遥,所以结果应该会得到 hello,村雨遥,可以看到 Swagger 测试中也给我返回了对应的结果,说明我们的接口测试成功!

注意:
如果在整合过程中出现如下错误:

org.springframework.context.ApplicationContextException:Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

这里可能是由于 Spring Boot 版本过高导致,我写作本文时,一开始使用的 SpringBoot 2.6.2 版本,所以出现了该错误,而当我将 SpringBoot 降级为 2.5.6 时,该错误就不再出现。所以如果你也出现了这个问题,也可以尝试降低 SpringBoot 版本来解决。

总结:

以上就是本文的所有内容了,主要对 Swagger 进行了简单介绍,并用 Spring Boot 集成 Swagger,同时还进行简单的测试。

到此这篇关于Spring Boot 集成 Swagger2构建 API文档的文章就介绍到这了,更多相关构建 API文档内容请搜索我们以前的文章或继续浏览下面的相关文章希望大家以后多多支持我们!

(0)

相关推荐

  • Spring Boot整合Mybatis Plus和Swagger2的教程详解

    前言:如果你是初学者,请完全按照我的教程以及代码来搭建(文末会附上完整的项目代码包,你可以直接下载我提供的完整项目代码包然后自行体验!),为了照顾初学者所以贴图比较多,请耐心跟着教程来,希望这个项目Demo能给你一些帮助,如果觉得写的还可以请给个关注和点赞,谢谢! 题外话:这是我第一篇用markdown来写的博文,格式不好的地方请见谅 一.pom.xml和application.yml 1.pom.xml中添加相关依赖,这里我把我的pom.xml代码贴出来 <?xml version="1

  • springboot项目配置swagger2示例详解

    swagger简介 Swagger是一款RESTful接口的文档在线自动生成.功能测试功能框架.一个规范和完整的框架,用于生成.描述.调用和可视化RESTful风格的Web服务,加上swagger-ui,可以有很好的呈现. 当我们在后台的接口修改了后,swagger可以实现自动的更新,而不需要人为的维护这个接口进行测试. 一.swagger2中常用的注解作用 注解 作用 @Api 修饰整个类,描述Controller的作用 ,表示标识这个类是swagger的资源 @ApiOperation 描述

  • SpringBoot集成Swagger2构建在线API文档的代码详解

    第一部分:代码集成 pom.xml <!--swagger2配置--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.4.0</version> </dependency> <dependency> <groupId>i

  • SpringBoot基于Swagger2构建API文档过程解析

    一.添加依赖 <!--SpringBoot使用Swagger2构建API文档的依赖--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version> </dependency> <dependency> <group

  • SpringBoot结合Swagger2自动生成api文档的方法

    首先在pom.xml中添加如下依赖,其它web,lombok等依赖自行添加 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version> </dependency> <dependency> <groupId>io.spri

  • SpringBoot整合Swagger2的完整过程记录

    目录 前言 一.Spring Boot Web 整合 Swagger2 过程 1.1.添加 Swagger2 相关依赖 1.2.配置 Swagger2 配置类 二.配置 Swagger2 接口常用注解 2.1.@Api 请求类说明 2.2.@ApiOperation 方法的说明 2.3.@ApiImplicitParams 和 @ApiImplicitParam 方法参数说明 2.4.@ApiResponses 和 @ApiResponse 方法返回值的说明 2.5.@ApiModel 和 @A

  • SpringBoot整合Swagger2的步骤详解

    简介 swagger是一个流行的API开发框架,这个框架以"开放API声明"(OpenAPI Specification,OAS)为基础, 对整个API的开发周期都提供了相应的解决方案,是一个非常庞大的项目(包括设计.编码和测试,几乎支持所有语言). springfox大致原理: springfox的大致原理就是,在项目启动的过种中,spring上下文在初始化的过程, 框架自动跟据配置加载一些swagger相关的bean到当前的上下文中,并自动扫描系统中可能需要生成api文档那些类,

  • Spring Boot 集成 Swagger2构建 API文档

    目录 一.Swagger是什么 1.SwaggerEditor 2.SwaggerUI 3.SwaggerCodegen 4.SwaggerUI 二.SpringBoot集成Swagger 1.创建SpringBoot项目 2.引入依赖 3.构建Swagger配置类 4.编写接口 5.查看并测试接口 前言: 不管你是从事前端还是后端开发,相信都难免被接口文档折磨过.如果你是一个前端开发者,可能你会经常发现后端给的接口文档跟实际代码有所出入.而假设你是一个后端开发者,你可能又会觉得自己开发后端接口

  • Spring boot集成swagger2生成接口文档的全过程

    一.Swagger介绍 Swagger是一个规范和完整的框架,用于生成.描述.调用和可视化RESTful风格的web服务.目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器.这个解释简单点来讲就是说,swagger是一款可以根据restful风格生成的接口开发文档,并且支持做测试的一款中间软件. 二.使用swagger优势 1.对于后端开发人员来说 不用再手写Wiki接口拼大量参数,避免手写错误 对代码侵入性低,采用全注解的方式,开发简单 方法参数名修改.

  • SpringBoot集成Swagger构建api文档的操作

    最近在做项目的时候,一直用一个叫做API的东西,controller注解我会写,这个东西我也会用,但是我确实不知道这个东西是个什么,有点神奇.关键还坑了我一次,他的注解会影响到代码的运行,不光是起到注解的作用.所以我就研究了一下. Swagger是什么:THE WORLD'S MOST POPULAR API TOOLING 根据官网的介绍: Swagger Inspector:测试API和生成OpenAPI的开发工具.Swagger Inspector的建立是为了解决开发者的三个主要目标. 1

  • Spring Boot集成Swagger2项目实战

    一.Swagger简介 上一篇文章中我们介绍了Spring Boot对Restful的支持,这篇文章我们继续讨论这个话题,不过,我们这里不再讨论Restful API如何实现,而是讨论Restful API文档的维护问题. 在日常的工作中,我们往往需要给前端(WEB端.IOS.Android)或者第三方提供接口,这个时候我们就需要给他们提供一份详细的API说明文档.但维护一份详细的文档可不是一件简单的事情.首先,编写一份详细的文档本身就是一件很费时费力的事情,另一方面,由于代码和文档是分离的,所

  • spring boot实现自动输出word文档功能的实例代码

    spring boot实现自动输出word文档功能 本文用到Apache POI组件 组件依赖在pom.xml文件中添加 <dependency> <groupId>org.apache.poi</groupId> <artifactId>poi</artifactId> <version>4.1.0</version> </dependency> <dependency> <groupId&

  • Spring Boot集成springfox-swagger2构建restful API的方法教程

    前言 之前跟大家分享了Spring MVC集成springfox-swagger2构建restful API,简单写了如何在springmvc中集成swagger2.这边记录下在springboot中如何集成swagger2.其实使用基本相同. 方法如下: 首先还是引用相关jar包.我使用的maven,在pom.xml中引用相关依赖(原来我使用的是2.2.0的,现在使用2.4.0的): <dependency> <groupId>io.springfox</groupId&g

  • SpringBoot集成Swagger2生成接口文档的方法示例

    我们提供Restful接口的时候,API文档是尤为的重要,它承载着对接口的定义,描述等.它还是和API消费方沟通的重要工具.在实际情况中由于接口和文档存放的位置不同,我们很难及时的去维护文档.个人在实际的工作中就遇到过很多接口更新了很久,但是文档却还是老版本的情况,其实在这个时候这份文档就已经失去了它存在的意义.而 Swagger 是目前我见过的最好的API文档生成工具,使用起来也很方便,还可以直接调试我们的API.我们今天就来看下 Swagger2 与 SpringBoot 的结合. 准备工作

  • Spring MVC集成springfox-swagger2构建restful API的方法详解

    前言 在集成springfox-swagger2之前,我也尝试着集成了swagger-springmvc,方式差不多,但是swagger-springmvc相对麻烦一点,因为要把它的静态文件copy到自己的项目中.所以还是用新版本的. 至于两者有什么不同,为什么进行版本变更请参见官方说明文档 方法如下 这里先写下需要的pom.xml配置(我引用的2.4.0,相对稳定) <dependency> <groupId>io.springfox</groupId> <ar

  • 详解Spring Boot实战之Restful API的构建

    上一篇文章讲解了通过Spring boot与JdbcTemplate.JPA和MyBatis的集成,实现对数据库的访问.今天主要给大家分享一下如何通过Spring boot向前端返回数据. 在现在的开发流程中,为了最大程度实现前后端的分离,通常后端接口只提供数据接口,由前端通过Ajax请求从后端获取数据并进行渲染再展示给用户.我们用的最多的方式就是后端会返回给前端一个JSON字符串,前端解析JSON字符串生成JavaScript的对象,然后再做处理.本文就来演示一下Spring boot如何实现

随机推荐