Swagger3学习笔记

已于 2022-02-13 17:28:35 修改
阅读量2k 收藏 7
点赞数 1
分类专栏： 笔记 文章标签： spring boot java maven api javaweb
于 2022-02-13 17:27:59 首次发布
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/weixin_45835256/article/details/122910913
版权

目录

一、简介

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文档：
在这里插入图片描述

C.kai
关注
  • 1
    点赞
  • 踩
  • 7
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
专栏目录
Swagger3配置使用-可用于生产环境
10-14
SpringFox 3.0.0集成示例，OpenAPI规范是一个由社区驱动的开放规范，这个规范定义了一个标准的、语言无关的 RESTful API 接口规范，它可以同时允许开发人员和操作系统查看并理解某个服务的功能，而无需访问源代码，文档或网络流量检查。合理地定义OpenAPI规范，能使开发者更好的理解远程服务和与之交互。目前最新的规范是OpenAPI Specification 3.0.3。
Swagger3的基本使用
YXXXYX的博客
05-27 2万+
Swagger3简介 swagger官网：传送门 swagger是一个Api框架，就是一个工具，就比如我们可以使用postman测试接口一样，swagger主要作用是生成RESTFUL接口的文档并且可以提供功能测试； 可以看一下官方文档简介： What Is Swagger? Swagger allows you to describe the structure of your APIs so that machines can read them. The ability of APIs to des
Swagger 3，花费近一年时间整理的Java核心知识清单
I8929545452_VD的博客
03-23 852
上述知识点，囊括了目前互联网企业的主流应用技术以及能让你成为“香饽饽”的高级架构知识，每个笔记里面几乎都带有实战内容。很多人担心学了容易忘，这里教你一个方法，那就是重复学习。打个比方，假如你正在学习 spring 注解，突然发现了一个注解@Aspect，不知道干什么用的，你可能会去查看源码或者通过博客学习，花了半小时终于弄懂了，下次又看到@Aspect 了，你有点郁闷了，上次好像在哪哪哪学习，你快速打开网页花了五分钟又学会了。从半小时和五分钟的对比中可以发现多学一次就离真正掌握知识又近了一步。
swagger3的配置和使用（一）
ErnestW的博客
04-06 5489
Swagger3.0配置和说明
SpringBoot——2.7.3版本整合Swagger3
quanzhan_King的博客
06-27 8417
Swagger2（基于openApi3）已经在17年停止维护了，取而代之的是 sagger3（基于openApi3），而国内几乎没有 sagger3使用的文档，百度搜出来的大部分都是swagger2的使用，这篇文章将介绍如何在 java 中使用 openApi3（swagger3）。
优雅的配置(升级)swagger3
hunt_er的博客
02-17 8400
Swagger目前最新版本是3.0.0,在Spring Boot应用中集成Swagger3比老的Swagger2简单的多。 以下讲解 适用于swagger2升级swagger3，及新版本直接采用swagger3的项目~。 作者现有的项目采用的是swagger2，升级swagger3的时候顺便学习了下。 swagger3配置项 1.依赖项 3的依赖相比2略有不同，不过都是springfox家的 <dependency> <groupId>io.springfox&
swagger学习笔记
05-25
swagger学习笔记
swagger学习笔记，最新swagger整合springboot
02-19
最新swagger2整合springboot
springboot学习笔记，适合新手
08-12
1、首先对Spring Boot做一个简单的介绍。 2、开发工具idea，构建工具maven。 3、然后我们会创建一个简单的Spring Boot应用程序。 4、然后会们会遵循一个流行的系统架构风格 RESTful 来开发我们应用...3、整合swagger
尚学堂Spring学习笔记
03-19
尚学堂Spring学习笔记.马士兵的，看了很受用，摘录了一些
Swagger.md，听的是b站狂神说的swagger教学
10-24
看狂神说的b站swagger视频，typroa笔记，超级详细
Swagger 3.0快速入门
m0_53157173的博客
08-06 1万+
Swagger快速入门一。Swagger简介1. 前后端分离2. Swagger引入springfox-swagger 2SpringFox 3.0.0 发布swagger3.0 与2.xx配置差异：具体使用教程如下1.导入依赖2.application.yml配置3.配置Swagger API信息4.修改默认API文档显示页面配置Swagger自定义扫描接口自定义扫描接口配置是否启动SwaggerSwagger只在生产环境下使用配置API文档分组1. 设置默认组名2. 配置多个组配置Model实体类只要我
Swagger3介绍和使用
华子的博客
04-16 1万+
Swagger3 OpenApi规范 地址：https://github.com/OAI/OpenAPI-Specification OpenAPI规范经过Reverb Technologies和SmartBear等 公司多年的发展，OpenAPI计划拥有该规范（捐赠之后）， OpenAPI Initiative在GitHub上托管社区驱动的规范。 规范是⼀种与语⾔⽆关的格式，⽤于描述RESTful Web服 务，应⽤程序可以解释⽣成的⽂件，这样才能⽣成代码、⽣成 ⽂档并根据其描述的服务创建模拟应⽤。 开放
Swagger3 使用介绍
总结分享
03-04 7488
迁移到SpringDoc确实是一个更好的选择。确实很好用，和之前熟悉的用法差不多，学习成本低。
Swagger 3 注解使用指南
吉屋安的博客
06-07 1万+
注解来描述每个API操作的摘要和详细描述，注解的对象，用于描述参数的数据类型。描述：用于描述操作的输入参数。在上述示例中，我们使用了。注解来描述请求体，以及。注解来描述响应结果，注解来描述路径参数，注解来描述响应结果。
Swagger注解-@ApiResponses 和 @ApiResponse
热门推荐
dejunyang的博客
04-27 7万+
@ApiResponses 使用场景 在 Rest 接口上使用，用作返回值的描述 概述 一个包装器，允许列出多个 ApiResponse，若果你需要描述单个 ApiResponse，你仍然必须使用此注解并将@ApiResponse 包装在一个数组中 属性 属性名称 数据类型 默认值 说明 value ApiResponse[] ApiResponse 列表 @ApiRespo...
SpringBoot集成Swagger3 —— 教你如何优雅的写文档
qq_22075913的博客
05-19 1万+
Swagger介绍及使用 导语： 相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。 Swagger简介
Swagger3 使用详解
初心不忘、始终方得
02-27 2573
swagger使用快速入门到实战
Swagger介绍及使用
Django的博客
01-28 1万+
Swagger介绍及使用 Swagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。 Swagger UI:提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以...
swagger3依赖包
最新发布
04-04
Swagger 3是Swagger的最新版本，它提供了一种简单而强大的方式来描述和定义API。 在使用Swagger 3时，你需要添加相应的依赖包。以下是Swagger 3的常用依赖包： 1. springfox-boot-starter：这是一个Spring Boot...

“相关推荐”对你有帮助么？

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

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

抵扣说明：

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

余额充值