Swagger3学习笔记

原创 已于 2022-02-13 17:28:35 修改 · 2.3k 阅读 · 9 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
文章标签：

#spring boot #java #maven #api #javaweb

于 2022-02-13 17:27:59 首次发布

目录

一、简介

Swagger是一个简单但功能强大的API表达工具。使用Swagger生成API，
我们可以得到交互式文档，自动生成代码的SDK以及API的发现特性等。
swagger官网
swagger在线编辑器

二、SpringBoot集成Swagger3

步骤：

1、新建springboot项目
2、导入swagger依赖Maven

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

这里用的是 springfox，Swagger 可以看作是一个遵循了 OpenAPI 规范的一项技术，而 springfox 则 是这项技术的具体实现。

3、开启swagger，在springboot启动类中添加@EnableOpenApi注解

@SpringBootApplication
@EnableOpenApi
public class SwaggerDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerDemoApplication.class, args);
    }
}

4、创建一个测试controller

@RestController
public class HelloController {
    @GetMapping(value = "/hello")
    public String hello(){
        return "hello";
    }
}

启动项目测试
在这里插入图片描述
注意：
springboot2.6.X启动项目会报Failed to start bean ‘documentationPluginsBootstrapper’; nested exception is java.lang.NullPointerException。
原因是：Springfox使用的路径匹配是基于AntPathMatcher的，而Spring Boot 2.6.X使用的是PathPatternMatcher。
解决办法： 在application.yml中添加以下配置

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

5、访问swagger接口文档 http://localhost:8080/swagger-ui/
在这里插入图片描述
6、展开HelloWorldController接口定义
在这里插入图片描述
展开hello接口
在这里插入图片描述
点击Try it out
在这里插入图片描述

三、Swagger3 常用注解

1.@Api

说明：用在处理类上，表示对类的说明
常用属性：

  • tags：描述该类的作用

2.@ApiOperation

说明：用在请求的方法上，说明方法的作用和备注
常用属性：

  • value：描述方法的作用
  • notes：备注说明

3.@ApiImplicitParams

说明：用在请求的方法上，表示一组参数说明

常用属性：

  • @ApiImplicitParams
    说明：定义参数各项信息
    常用属性：
    • name：参数名称
    • value：参数说明
    • required：是否必传，值为Boolean类型
    • paramType：参数放在哪个地方，常用值为：query（放在请求参数中，@RequestParam获取参数）、header（放在请求头中，@RequestHeader获取参数）、path（用于restful接口，@PathVariable获取参数）
    • dataType：参数类型，默认String
    • defaultValue：参数的默认值

4.@ApiResponses

说明：用在请求的方法上，表示一组响应
常用属性：

  • @ApiResponse
    说明：一般用于表达一个错误的响应信息
    常用属性：
    • code：响应码
    • message：响应信息
    • response：抛出异常的类

5.@ApiModel

说明：用于响应类上，描述响应的数据对象

6.@ApiModelProperty

说明：用在JavaBean属性上，描述响应类的属性或请求类的属性
常用属性：

  • name：参数名称
  • value：参数说明
  • required：是否必传，值为Boolean类型
  • dataType：参数类型，默认String

示例一：@Api、@ApiOperation

@RestController
@Api(tags = "Hello测试处理器")
public class HelloController {
    @ApiOperation(value = "hello接口", notes = "<h1>这是备注说明</h1>")
    @GetMapping(value = "/hello")
    public String Description() {
        return "hello";
    }
}

在这里插入图片描述

示例二：@ApiImplicitParams

@RestController
@Api(tags = "Hello测试处理器")
public class HelloController {
    @PostMapping(value = "/findInfo")
    @ApiOperation(value = "查询信息", notes = "<h1>这是备注说明</h1>")
    @ApiImplicitParams(value = {
        @ApiImplicitParam(name = "value", value = "值", required = true, paramType = "query"),
        @ApiImplicitParam(name = "id", value = "编号", required = true, paramType = "query", dataType = "Integer")
    })
    public String findInfo(String value, Integer id) {
        return value + "====" + id;
    }
}

在这里插入图片描述

示例三：@ApiResponses、@ApiModel、@ApiModelProperty

@RestController
@Api(tags = "Hello测试处理器")
public class HelloController {
    @GetMapping("/getStudent/{id}")
    @ApiOperation(value = "获取学生信息", notes = "<h1>这是备注说明</h1>")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "编号", required = true, paramType = "path", dataType = "Integer")
    })
    @ApiResponses({
        @ApiResponse(code = 600, message = "业务错误"),
        @ApiResponse(code = 404, message = "找不到路径"),
        @ApiResponse(code = 400, message = "参数错误"),
        @ApiResponse(code = 500, message = "程序错误")
    })
    public Student getStudent(@PathVariable("id") Integer id) {
        Student student = new Student();
        student.setId(id);
        student.setName("张三");
        student.setAge(25);
        student.setEmail("qwe@123");
        return student;
    }
}

Student.java

@ApiModel("学生实体信息")
public class Student {
    @ApiModelProperty(name = "id", value = "编号", dataType = "Integer")
    private Integer id;

    @ApiModelProperty(name = "name", value = "姓名", required = true, dataType = "String")
    private String name;

    @ApiModelProperty(name = "age", value = "年龄", required = true, dataType = "Integer")
    private Integer age;

    @ApiModelProperty(name = "email", value = "邮箱", required = true, dataType = "String")
    private String email;
}

在这里插入图片描述

四、API信息配置

默认情况，显示的API信息如下
在这里插入图片描述
修改默认配置，可以新建一个Java Config重写ApiConfig以及Docket来实现

@Configuration
public class Swagger3Config {
    /**
     * 配置Docket
     * @return
     */
    @Bean
    public Docket createDocket() {
        return new Docket(DocumentationType.OAS_30) // 指定swagger3.0版本
            .apiInfo(createApiInfo());
    }

    /**
     * 配置Docket
     * @return
     */
    @Bean
    public ApiInfo createApiInfo() {
        return new ApiInfo(
            "CK Swagger Document",
            "CK API Document",
            "0.0.1",
            "urn:tos",
            new Contact("CK", "http://localhost:8080/", "123456@163.com"),
            "Apache 2.0",
            "http://www.apache.org/licenses/LICENSE-2.0",
            new ArrayList<>()
        );
    }
}

通过ApiInfo源码查看构造参数

public ApiInfo(String title, String description, String version, String termsOfServiceUrl, Contact contact, String license, String licenseUrl, Collection<VendorExtension> vendorExtensions) {
    this.title = title;
    this.description = description;
    this.version = version;
    this.termsOfServiceUrl = termsOfServiceUrl;
    this.contact = contact;
    this.license = license;
    this.licenseUrl = licenseUrl;
    this.vendorExtensions = new ArrayList(vendorExtensions);
}

在这里插入图片描述

五、Docket 开关&过滤&分组配置

通过设置Docket，可以配置很多功能，比如是否开启swagger，过滤，分组等；

1.Docket开关设置

一般情况，只有在开发环境才会用到swagger，正式环境需要关闭swagger，一个是安全问题，还有一个是用了swagger会影响系统运行速度；

通过配置Docket对象的enable方法实现swagger启用和禁用

/**
     * 配置Docket
     * @return
     */
@Bean
public Docket createDocket() {
    return new Docket(DocumentationType.OAS_30)
        .apiInfo(createApiInfo())
        .enable(false);
}

重启后在访问，可以看到已经被禁用了
在这里插入图片描述

2.设置过滤API

有些情况，我们需要指定包路径下的类生成API，或者根据前端用户路径请求过滤；
使用过滤要调用select()方法，select()方法有两种方法实现过滤：
1、根据包路径来扫描指定类的API
具体示例：

/**
     * 配置Docket
     * @return
     */
@Bean
public Docket createDocket() {
    return new Docket(DocumentationType.OAS_30) // 指定swagger3.0版本
        .apiInfo(createApiInfo())
        .enable(true)
        //设置过滤
        .select()
        //RequestHandlerSelectors.basePackage()设置包路径来扫描指定类的API；any() 方法是默认所有都有效， none()方法都无效；withClassAnnotation()根据类注解， withMethodAnnotation()是根据方法注解；
        .apis(RequestHandlerSelectors.basePackage("com.example.swaggerdemo.controller.test1"))
        //最后加build()方法
        .build();
}

2、根据请求路径来扫描API
具体示例：

/**
     * 配置Docket
     * @return
     */
@Bean
public Docket createDocket() {
    return new Docket(DocumentationType.OAS_30) // 指定swagger3.0版本
        .apiInfo(createApiInfo())
        .enable(true)
        //设置过滤
        .select()
        //PathSelectors.ant()设置匹配路径；any()是匹配任意路径， none()是都不匹配， regex()是正则匹配；
        .paths(PathSelectors.ant("/test1/**"))
        .build();
}

3.设置分组

在实际项目开发中，把复杂项目划分多模块给多个小组或者多个人负责开发，所以每个小组或者个人要 实现自己的分组，方便查找到API接口开发负责人，沟通和处理问题；

通过配置Docket对象的groupName方法设置组名；

/**
     * 配置Docket
     * @return
     */
@Bean
public Docket createDocket() {
    return new Docket(DocumentationType.OAS_30) // 指定swagger3.0版本
        .apiInfo(createApiInfo())
        .enable(true)
        .groupName("Group A");
}

重启项目，默认组名改为了Group A
在这里插入图片描述

配置多个组

在controller包下创建两个子包并创建Controller，模拟两个模块
在这里插入图片描述
在Swagger3配置类中配置两个Docket和ApiInfo，通过Docket对象的apis方法为每个组扫描指定包下的API；
具体代码：

package com.example.swaggerdemo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
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 java.util.ArrayList;

@Configuration
public class Swagger3Config {
    /**
     * 配置DocketA
     * @return
     */
    @Bean
    public Docket createDocketA() {
        return new Docket(DocumentationType.OAS_30) // 指定swagger3.0版本
            .apiInfo(createApiInfoA())
            .enable(true)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.swaggerdemo.controller.test1"))
            .build()
            .groupName("Group A");
    }

    /**
     * 配置DocketB
     * @return
     */
    @Bean
    public Docket createDocketB() {
        return new Docket(DocumentationType.OAS_30) // 指定swagger3.0版本
            .apiInfo(createApiInfoB())
            .enable(true)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.swaggerdemo.controller.test2"))
            .build()
            .groupName("Group B");
    }

    /**
     * 配置ApiInfoA
     * @return
     */
    @Bean
    public ApiInfo createApiInfoA() {
        return new ApiInfo(
            "CK GroupA Swagger Document",
            "CK API Document",
            "0.0.1",
            "urn:tos",
            new Contact("CK", "http://localhost:8080/", "123456@163.com"),
            "Apache 2.0",
            "http://www.apache.org/licenses/LICENSE-2.0",
            new ArrayList<>()
        );
    }

    /**
     * 配置ApiInfoB
     * @return
     */
    @Bean
    public ApiInfo createApiInfoB() {
        return new ApiInfo(
            "CK Swagger Document",
            "CK GroupB API Document",
            "0.0.1",
            "urn:tos",
            new Contact("CK", "http://localhost:8080/", "123456@163.com"),
            "Apache 2.0",
            "http://www.apache.org/licenses/LICENSE-2.0",
            new ArrayList<>()
        );
    }
}

重启项目
在这里插入图片描述
组Group A的API文档：
在这里插入图片描述
组Group B的API文档：
在这里插入图片描述

ApiResponse response = *.class不起作用
猿小白的博客
05-27 1878
此处添加了ApiResponse注解，但在swagger中的响应依然没有数据 目录 一、原因分析 二、解决办法 （1）创建一个泛型实体类 （2）编写一个测试接口 三、再次访问Swagger接口 一、原因分析 AjaxResult是继承的map，Swagger只认识定义好的类-属性，所以接口返回Map,对于Swagger来说是没有字段展示的。 二、解决办法 如需要可以使用泛型类R<T>来解决这个问题。 （1）创建一个泛型实体类 packag...
Spring Boot整合Swagger3(OpenAPI3)生成接口文档
weixin_42759726的博客
07-17 9222
都说好记性不如烂笔头,每天写一点,从量变到质变的开始!废话不多说,以下所有内容均来自本人实际操作: 1.为什么使用Swagger3(OpenAPI3)? swagger官方文档介绍的功能太过复杂,作为一个后端开发,我们往往只需要用它来自动生成接口文档,而Swagger2早就不维护了,因此通过这篇博客找到了springdoc官网 springdoc-openapi Java库有助于使用Spring Boot项目自动生成API文档.springdoc-openapi的工作原理是在运行时检查应用程序,以基于
Swagger3配置使用-可用于生产环境
10-14
SpringFox 3.0.0集成示例，OpenAPI规范是一个由社区驱动的开放规范，这个规范定义了一个标准的、语言无关的 RESTful API 接口规范，它可以同时允许开发人员和操作系统查看并理解某个服务的功能，而无需访问源代码，文档或网络流量检查。合理地定义OpenAPI规范，能使开发者更好的理解远程服务和与之交互。目前最新的规范是OpenAPI Specification 3.0.3。
SpringBoot集成Swagger3.0（详细）
最新发布
chuixue24的博客
11-05 163
本文介绍了在SpringBoot项目中集成Swagger3.0(OpenAPI3.0)框架的具体实现。主要内容包括：Swagger发展历程概述，重点对比了1.x、2.x和3.x版本的区别；详细说明了通过springdoc-openapi-ui工具集成Swagger3.0的步骤，包括Maven依赖配置、全局API文档设置（支持配置类和注解两种方式）；具体讲解了API接口的定义方法，包括@Tag、@Operation等核心注解的使用；最后演示了权限认证配置和运行效果展示。文中提供了完整的代码示例，帮助开发者快速
Swagger 3 注解使用指南
热门推荐
吉屋安的博客
06-07 2万+
注解来描述每个API操作的摘要和详细描述，注解的对象，用于描述参数的数据类型。描述：用于描述操作的输入参数。在上述示例中，我们使用了。注解来描述请求体，以及。注解来描述响应结果，注解来描述路径参数，注解来描述响应结果。
SpringBoot3使用Swagger3
Q95470的博客
06-17 5049
Swagger是一个用于设计、构建、文档化和使用RESTful Web服务的开源工具。Swagger3是Swagger的最新版本，它提供了许多新功能和改进。Swagger在SpringBoot3中的引入方法发生了改变,网上大部分还是SpringBoot2的版本。访问http://localhost:9090/swagger-ui/index.html#/其中的9090 改成你项目后端使用的端口，注意不能省略后面的index.html。版本也可以使用新版，Springdoc-OpenAPI。
swagger学习笔记
05-25
swagger学习笔记
swagger学习笔记，最新swagger整合springboot
02-19
Swagger学习笔记，最新Swagger整合Spring Boot Swagger是一种基于OpenAPI规范的API文档生成工具，能够自动生成API文档、客户端SDK、服务器stub等。本文将介绍如何将Swagger整合到Spring Boot项目中，以生成API文档...
spring boot(学习笔记第十九课) batch框架，以及Swagger3(OpenAPI)整合
sealaugh32的专栏
08-27 1812
OpenAPI。
swagger自学项目笔记
07-08
3. **Swagger UI**：这是一个Web界面，用于展示由Swagger解析的API文档。开发者可以通过Swagger UI直观地看到API的结构，进行测试和调试。 4. **Swagger Codegen**：这是一个工具，可以自动生成客户端SDK、服务器端...
Swagger笔记
大胆刁民的博客
07-26 1299
Swagger 文章目录SwaggerSwagger简介swagger使用配置Swagger第一步：第二步：第三步第四步第五步第六步配置扫描接口演示：配置Swagger开关演示：配置API分组单组：单个组演示：多组多组演示：常用注解演示注解的注释作用和模拟传参 Swagger简介 前后端分离 前端 -> 前端控制层、视图层 后端 -> 后端控制层、服务层、数据访问层 前后端通过API进行交互 前后端相对独立且松耦合 产生的问题 前后端集成，前端或者后端无法做到“及时协商，尽早解决”，最
Swagger3
xiaotu的博客
04-17 2583
Swagger 是一系列 RESTful API 的工具，通过 Swagger 可以获得项目的⼀种交互式文档，客户端 SDK 的自动生成等功能。Swagger 的目标是为 REST APIs 定义一个标准的、与语⾔言无关的接口，使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下，能发现和理解各种服务的功能。当服务通过 Swagger 定义，消费者就能与远程的服务互动通过少量的实现逻辑。Swagger（丝袜哥）是世界上最流行的 API 表达工具。了解。
swagger3
qq_36022463的博客
10-13 951
swagger 用于生成，描述，调用，可视化 RESTFUL风格的web服务。 在swargger2中需要导两个依赖： <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dep
SpringBoot-Swagger3
qq_44989062的博客
09-02 2243
swagger
swagger3(openapi)
fengyifanjin的博客
01-26 1391
之前写了一篇基于swagger2版本常用的注解(不太详细)，现在更新一版swagger3(openapi)版本的内容，用于后续使用查阅。
Swagger3.0.0
weixin_45365220的博客
03-31 2340
作为一个RESTful风格的可视化框架，经常会和yapi作个比较， 相比于yapi其优势展现在： 自动实时更新接口信息 更强大的接口信息描述注解 劣势在于： 代码侵入性强 UI不如Yapi好看（当然swagger的UI页面支持引入更换，且swagger3的UI比以往版本好看一些） Yapi还有权限管理、团队协作、自动化测试等功能 Swagger3目前已经将注解规范化，基于openApi3，且兼容以往版本的注解和配置 今天我们来看看简单的Swagger3版本整合到springboot项目中 pom依赖
Spring Boot之Swagger 3.0
拾一二的博客
12-26 2862
目录 前言 ​ 什么是Swagger 有用的链接 项目集成 1、添加依赖 2、启动类配置 3、启动项目 分组 第一步：添加Swagger3自定义配置类（可选） 第二步：属性文件配置 授权 如何添加授权信息？ 如何携带公共的请求参数？ 格式美化 第一步：添加bootstrap-ui支持 第二步：启动项目 注解说明 示例代码 注解 前言 这是一个突破性的变更 有关此项目的更多信息，请访问API Documentation & Design To...
Swagger @Content
02-21
### 如何在 Swagger 中使用 `@Content` 注解 `@Content` 注解主要用于描述 API 操作的响应体或请求体的内容结构。该注解通常与其他注解一起使用，比如 `@RequestBody` 或者 `@ApiResponse` 来定义具体的媒体类型以及对应的模式(schema)[^2]。 #### 定义响应内容 当希望为某个 HTTP 方法返回的数据指定具体格式时，可以通过 `@Content` 提供这些细节： ```java import io.swagger.v3.oas.annotations.media.Content; import io.swagger.v3.oas.annotations.responses.ApiResponse; // ... @ApiResponse(responseCode = "200", description = "Successful operation", content = @Content(mediaType = "application/json")) public ResponseEntity<User> getUserById(@PathVariable("id") Long id) { // method implementation... } ``` 上述例子展示了如何设置成功响应的状态码、说明文字及预期返回 JSON 数据类型的配置。 #### 结合 `@Schema` 描述复杂对象 对于复杂的业务实体类（如 User），还可以进一步利用 `@Schema` 对象来精确表达其内部字段的信息： ```java import io.swagger.v3.oas.annotations.media.Schema; import io.swagger.v3.oas.annotations.media.Content; import io.swagger.v3.oas.annotations.responses.ApiResponse; // ... @ApiResponse(responseCode = "200", description = "Successfully retrieved user details.", content = @Content( mediaType = "application/json", schema = @Schema(implementation = User.class))) public ResponseEntity<User> getUserById(@PathVariable("id") Long id) { // method implementation... } ``` 这里不仅指定了 MIME 类型为 application/json ，还关联了一个 Java Bean (`User`) 的 Schema 表达方式给客户端展示完整的模型信息。 #### 处理多种可能的结果集 有时同一个接口可能会有不同形式的成功回复或者是错误提示，在这种情况下可以传递多个 `@Content` 实例到父级注解中去覆盖各种情况下的表现形态： ```java import java.util.Arrays; import org.springframework.http.ResponseEntity; import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.Parameter; import io.swagger.v3.oas.annotations.media.ArraySchema; import io.swagger.v3.oas.annotations.media.Content; import io.swagger.v3.oas.annotations.media.Schema; import io.swagger.v3.oas.annotations.parameters.RequestBody; import io.swagger.v3.oas.annotations.responses.ApiResponse; //... @Operation(summary = "Create new users with the provided information.") @PostMapping("/users") @ApiResponse(responseCode = "201", description = "Created successfully.", content = {@Content(mediaType="application/json", array=@ArraySchema(schema=@Schema(implementation=User.class)))}) @ApiResponse(responseCode = "400", description = "Invalid input data.", content = @Content(mediaType = "application/json", schema = @Schema(type = "object"))) public ResponseEntity<String> createUser(@Valid @RequestBody(required=true, content=@Content(mediaType="application/json", schema=@Schema(implementation=NewUserRequest.class))) NewUserRequest newUser){ // Implementation here ... } ``` 这段代码片段显示了创建新用户的 POST 请求处理逻辑，并针对不同的状态码提供了相应的 Content 配置。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值