Spring Boot demo系列(七):Swagger

原创
09/23 23:49
阅读数 37

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/

会出现如下界面:

在这里插入图片描述

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

在这里插入图片描述

或者直接访问:

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";
    }
}

在这里插入图片描述

运行后可以看到多了一个接口,也就是@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;
}

效果如图:

在这里插入图片描述

在这里插入图片描述

在这里插入图片描述

在这里插入图片描述

7 参考源码

Java版:

Kotlin版:

展开阅读全文
打赏
0
0 收藏
分享
加载中
更多评论
打赏
0 评论
0 收藏
0
分享
OSCHINA
登录后可查看更多优质内容
返回顶部
顶部