Swagger 3.0

最新推荐文章于 2024-06-13 09:34:45 发布

JamesAks

最新推荐文章于 2024-06-13 09:34:45 发布

阅读量396

点赞数

文章标签： java ui 开发语言 spring spring boot

本文链接：https://blog.csdn.net/m0_64332518/article/details/129706724

版权

Swagger 3.0

本swagger之以org.springdoc来学习，spring boot和swagger依赖关系springdoc.org
官网地址：API Documentation & Design Tools for Teams | Swagger

依赖

spring boot 2.x整合swagger 3.0 的maven依赖

 <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>1.6.15</version>
        </dependency>
<!--	swagger需要的webjars依赖	-->
		<dependency>
			<groupId>org.webjars</groupId>
			<artifactId>jquery</artifactId>
			<version>3.6.2</version>
		</dependency>

spring boot 3.x整合swagger 3.0 的maven依赖

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

1：swagger是什么

OpenAPI是规范；Swagger是实现规范的工具

open api 简介
OpenApi是一个业界的 api 文档标准，一个规范。

好比java里面一个抽象的概念，即是一个抽象类，只是提供了一个api文档规范的抽象方法。

该方法目前被两大非官方实现了，一个是springfox，另一个是springdoc。

最流行的api框架
可以在线、自动、更新生成api文档生成器，来自于前后端分离
可以在线测试api接口
可以和很多技术使用

2：swagger-ui

没有设置项目地址默认就是http://localhost:8080/swagger-ui/index.html

2.1swagger自定义页面

配置一个注解只保留有用的页面信息

效果

在这里插入图片描述

注解

@OpenAPIDefinition(
        info = @Info(title = "用户登录API文档",description = "测试API文档",version = "version-1.0",
                contact = @Contact(name = "xxl",email = "3578144921@qq.com",url = "https://gitee.com/com_xxl/spring-boot-study")),
    	//这个服务地址就是swagger-ui测试接口的地址
        servers = @Server(url = "http://localhost:8080/",description = "默认地址")
)

3：spring-boot-swagger注解

3.1、@EnableSwagger2

开启swagger 功能，让swagger 注解生效但版本是2.0

范围

@Target(value = {java.lang.annotation.ElementType.TYPE})

3.2、@OpenAPIDefinition

范围

@Target({ElementType.TYPE, ElementType.PACKAGE, ElementType.ANNOTATION_TYPE})

@OpenAPIDefinition全局只能定义一个，主要配置文档信息和安全配置，这里列举了常用的请求头携带token的安全配置模式
@OpenAPIDefinition下的info属性配置文档信息
@OpenAPIDefinition下的security配置认证方式，name属性引入自定义的认证模式
@SecurityScheme注解就是自定义的认证模式，配置请求头携带token

3.3、@Tag

范围

@Target({ElementType.METHOD, ElementType.TYPE, ElementType.ANNOTATION_TYPE})

常用属性

@Tag(name = "接口名字", description = "接口描述") //针对类、接口

如果注解了java接口，这个接口又被controller继承了则会包含controller的请求路径

在这里插入图片描述

3.4、 @Operation

此注解包含@Parameter，@ApiResponse
描述方法的注解

范围

@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})

在这里插入图片描述

Api类

@Operation(
        summary = "登录接口",
        description = "用于用户登录的接口"
)
String login(String username,String password);

3.5、@Schema

暂时的用法就是用在dto对象

范围

@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.TYPE, ElementType.ANNOTATION_TYPE})

描述对象信息

swagger-ui

实体类

@Data
@AllArgsConstructor
@NoArgsConstructor
@Schema(name = "User" ,title = "用户数据传输对象")
public class User {
    @Schema(title = "用户姓名")
    private String name;
    @Schema(title = "用户爱好")
    private String hobby;
}

3.6、@ApiResponse

设置返回什么，建议用在方法上

范围

@Target({ElementType.METHOD, ElementType.TYPE, ElementType.ANNOTATION_TYPE})

如果配合@ControlleerAdvice使用，如全局的异常类捕捉了400的错误就会加入所有方法中，然后会被记录在swagger-ui

案例

@ApiResponse(description = "登录成功",content = @Content(mediaType = "application/json;charset=utf-8"),responseCode = "200")
@ApiResponse(description = "页面未找到",content = @Content(mediaType = "application/json;charset=utf-8"),responseCode = "404")
@ApiResponse(description = "服务器代码错误",content = @Content(mediaType = "application/json;charset=utf-8"),responseCode = "500")
 String login(String username,String password);

3.7、@Parameter

描述属性、参数信息，一般用于参数的描述
name与参数名一致

范围

@Target({PARAMETER, METHOD, FIELD, ANNOTATION_TYPE})

在这里插入图片描述

案例

@Parameter(name = "username",description = "用户名",required = false)
@Parameter(name = "password",description = "用户密码",required = false)
String login(String username,String password);

4：spring-boot-swagger的yml配置文件

比较常用的

springdoc:
  api-docs:
  #是否开启文档功能关系到swagger-ui能否开启
    enabled: true
  #swagger后端请求地址，查看sawgger所有配置
    path: /api-docs
  swagger-ui:
    #自定义swagger前端请求路径，输入http：127.0.0.1:8080/test会自动重定向到swagger页面
    path: /test
  #包扫描路径，注册api，
#  packages-to-scan:  "com.xxl.controller"
  #这里定义了两个分组，可定义多个，也可以不定义
  group-configs:
      #分组名
  - group: admin
    #按包路径匹配：范围大
    packagesToScan:  "com.xxl.controller.impl"
    #分组名
  - group: user
    #按请求路径匹配：范围小
    paths-to-match: "/user/**"
    #排除请求路径
    packages-to-exclude:
      - "/admin"

5：spring-boot-swagger

自动识别有没有请求，比如你写了controller但是没有设置请求路径，哪怕你加上了swagger注解在ui界面不会显示信息的，因为ui的信息根据请求路径来的
swagger 3-ui在spring-boot中能自动识别swagger注解(只有@Schemas比较特殊)因为只要被spring管理加上是控制器就会自动识别，并不需要开启什么
如果接口使用了实体类就会被识别，在swagger-ui的Schemas区域
可以配合jsr303使用