Spring Boot demo系列(八):Swagger

Stella981
• 阅读 1319

2021.2.24 更新

1 概述

Swagger主要用于生成API文档,本文演示了如何使用目前最新的OpenAPI3以及Swagger来进行接口文档的生成。

2 依赖

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.4.7</version>
</dependency>

Gradle

implementation( "org.springdoc:springdoc-openapi-ui:1.4.7")

3 配置

Swagger的配置很简单,仅需要一个@OpenAPIDefinition即可,@OpenAPIDefinition用于描述全局的配置信息,参考配置如下:

  • info表示基本信息,比如标题,版本,描述等

  • externalDocs是参考文档

  • servers是服务器地址

    @OpenAPIDefinition(info = @Info(title = "标题",version = "版本",description = "描述"), externalDocs = @ExternalDocumentation(description = "参考文档",url = "https://www.baidu.com"), servers = @Server(url = "http://localhost:8080")) public class SwaggerConfig { }

接着在配置文件写上文档路径:

springdoc:
  api-docs:
    path: /doc

4 访问

运行后直接访问

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

会出现如下界面:

Spring Boot demo系列(八):Swagger

搜索栏中输入配置文件中的路径/doc搜索即可:

Spring Boot demo系列(八):Swagger

或者直接访问:

http://localhost:8080/swagger-ui/index.html?url=/doc

5 控制器

下一步就是添加具体的接口,先来看一个简单的例子:

@RestController
@Tag(name = "测试Controller")
@RequestMapping("/")
public class TestController {
    @GetMapping("test")
    @Operation(description = "测试接口",tags = "测试Controller")
    public String test()
    {
        return "success";
    }
}

Spring Boot demo系列(八):Swagger

运行后可以看到多了一个接口,也就是@Tag@Operation起作用了,注解说明如下:

  • @Tag表示标签,name指定标签的值,也可以加上description等属性
  • @Operation作用在方法上,可以指定描述以及标签,也可以指定参数以及返回值等信息

类似的注解还有很多,比如:

  • @Parameter:指定参数属性,比如descriptionname
  • @ApiResponse:指定返回值,常用的属性有responseCode以及description
  • @Schema:用在实体类上以及实体类字段上,在接口上可以显示对应的值

6 完整示例

下面是一个接口控制器的完整示例:

@RestController
@Tag(name = "测试Controller")
@RequestMapping("/")
public class TestController {
    @GetMapping("test")
    @Operation(description = "测试接口",tags = {"测试Controller","测试"})
    public String test()
    {
        return "success";
    }

    @GetMapping("test2")
    @Operation(description = "这个也是测试接口",tags = {"测试Controller","2号测试接口"})
    @Parameter(description = "必要参数",name = "parm")
    public String test2(@RequestParam String parm)
    {
        return "需要参数";
    }

    @GetMapping("test3")
    @Operation(description = "带有返回状态的接口",tags = {"测试Controller"})
    @ApiResponse(responseCode = "111",description = "测试成功")
    @ApiResponse(responseCode = "222",description = "测试失败")
    public void test3(@RequestBody String body)
    {
    }

    @GetMapping("test4")
    @Operation(description = "User接口",tags = {"测试Controller"})
    @ApiResponse(responseCode = "100",description = "添加成功")
    public void test4(@RequestBody User user)
    {
    }
}

实体类:

@Getter
@Schema(description = "用户")
public class User {
    @Schema(description = "用户名")
    private String name;
    @Schema(description = "主键")
    private String id;
}

效果如图:

Spring Boot demo系列(八):Swagger

Spring Boot demo系列(八):Swagger

Spring Boot demo系列(八):Swagger

Spring Boot demo系列(八):Swagger

7 参考源码

Java版:

Kotlin版:

点赞
收藏
评论区
推荐文章
blmius blmius
3年前
MySQL:[Err] 1292 - Incorrect datetime value: ‘0000-00-00 00:00:00‘ for column ‘CREATE_TIME‘ at row 1
文章目录问题用navicat导入数据时,报错:原因这是因为当前的MySQL不支持datetime为0的情况。解决修改sql\mode:sql\mode:SQLMode定义了MySQL应支持的SQL语法、数据校验等,这样可以更容易地在不同的环境中使用MySQL。全局s
Easter79 Easter79
3年前
swap空间的增减方法
(1)增大swap空间去激活swap交换区:swapoff v /dev/vg00/lvswap扩展交换lv:lvextend L 10G /dev/vg00/lvswap重新生成swap交换区:mkswap /dev/vg00/lvswap激活新生成的交换区:swapon v /dev/vg00/lvswap
皕杰报表之UUID
​在我们用皕杰报表工具设计填报报表时,如何在新增行里自动增加id呢?能新增整数排序id吗?目前可以在新增行里自动增加id,但只能用uuid函数增加UUID编码,不能新增整数排序id。uuid函数说明:获取一个UUID,可以在填报表中用来创建数据ID语法:uuid()或uuid(sep)参数说明:sep布尔值,生成的uuid中是否包含分隔符'',缺省为
待兔 待兔
3个月前
手写Java HashMap源码
HashMap的使用教程HashMap的使用教程HashMap的使用教程HashMap的使用教程HashMap的使用教程22
Jacquelyn38 Jacquelyn38
3年前
2020年前端实用代码段,为你的工作保驾护航
有空的时候,自己总结了几个代码段,在开发中也经常使用,谢谢。1、使用解构获取json数据let jsonData  id: 1,status: "OK",data: 'a', 'b';let  id, status, data: number   jsonData;console.log(id, status, number )
Stella981 Stella981
3年前
IDEA Spring使用Swagger2 API接口
根据Swagger2可以快速帮助我们编写最新的API接口文档,再也不用担心开会前仍忙于整理各种资料了,间接提升了团队开发的沟通效率。1\.引入依赖<!Swagger2api接口插件<dependency<groupIdio.springfox</groupId
Stella981 Stella981
3年前
SpringBoot整合Swagger3生成接口文档
  前后端分离的项目,接口文档的存在十分重要。与手动编写接口文档不同,swagger是一个自动生成接口文档的工具,在需求不断变更的环境下,手动编写文档的效率实在太低。与新版的swagger3相比swagger2配置更少,使用更加方便。一、pom文件中引入Swagger3依赖<dependency
Easter79 Easter79
3年前
SpringBoot整合Swagger3生成接口文档
  前后端分离的项目,接口文档的存在十分重要。与手动编写接口文档不同,swagger是一个自动生成接口文档的工具,在需求不断变更的环境下,手动编写文档的效率实在太低。与新版的swagger3相比swagger2配置更少,使用更加方便。一、pom文件中引入Swagger3依赖<dependency
Wesley13 Wesley13
3年前
MySQL部分从库上面因为大量的临时表tmp_table造成慢查询
背景描述Time:20190124T00:08:14.70572408:00User@Host:@Id:Schema:sentrymetaLast_errno:0Killed:0Query_time:0.315758Lock_
Python进阶者 Python进阶者
9个月前
Excel中这日期老是出来00:00:00,怎么用Pandas把这个去除
大家好,我是皮皮。一、前言前几天在Python白银交流群【上海新年人】问了一个Pandas数据筛选的问题。问题如下:这日期老是出来00:00:00,怎么把这个去除。二、实现过程后来【论草莓如何成为冻干莓】给了一个思路和代码如下:pd.toexcel之前把这