百度360必应搜狗淘宝本站头条
python判断字典是否为空crontab每周一执行aes和des区别安装指定版本npmadb pull
当前位置：网站首页 > IT知识 > 正文

Swagger3.0官方starte诞生了其它的都可以扔了

liuian 2025-02-26 12:45 9 浏览

  • 资料
  • swagger介绍
  • springfox介绍
  • SpringFox 3.0.0 发布
  • 整合使用
  • 一些常用注解说明
  • 示例
  • 参考

资料

  • swagger 官网：swagger.io
  • springfox 官网：springfox
  • springfox Github 仓库：springfox / springfox
  • springfox-demos Github 仓库：springfox / springfox-demos
  • springfox Maven 仓库：Home ? io.springfox

swagger介绍

对于 Rest API 来说很重要的一部分内容就是文档，Swagger 为我们提供了一套通过代码和注解自动生成文档的方法，这一点对于保证 API 文档的及时性将有很大的帮助。

Swagger 是一套基于 OpenAPI 规范（OpenAPI Specification，OAS）构建的开源工具，可以帮助我们设计、构建、记录以及使用 Rest API。

OAS本身是一个API规范，它用于描述一整套API接口，包括一个接口是哪种请求方式、哪些参数、哪些header等，都会被包括在这个文件中。它在设计的时候通常是YAML格式，这种格式书写起来比较方便，而在网络中传输时又会以json形式居多，因为json的通用性比较强。

Swagger 主要包含了以下三个部分：

  • Swagger Editor：基于浏览器的编辑器，我们可以使用它编写我们 OpenAPI 规范。
  • Swagger UI：它会将我们编写的 OpenAPI 规范呈现为交互式的 API 文档，后文我将使用浏览器来查看并且操作我们的 Rest API。
  • Swagger Codegen：它可以通过为 OpenAPI（以前称为 Swagger）规范定义的任何 API 生成服务器存根和客户端 SDK 来简化构建过程。

springfox介绍

由于Spring的流行，Marty Pitt编写了一个基于Spring的组件swagger-springmvc，用于将swagger集成到springmvc中来，而springfox则是从这个组件发展而来。

通常SpringBoot项目整合swagger需要用到两个依赖：springfox-swagger2和springfox-swagger-ui，用于自动生成swagger文档。

  • springfox-swagger2：这个组件的功能用于帮助我们自动生成描述API的json文件
  • springfox-swagger-ui：就是将描述API的json文件解析出来，用一种更友好的方式呈现出来。

SpringFox 3.0.0 发布

官方说明：

  • SpringFox 3.0.0 发布了，SpringFox 的前身是 swagger-springmvc，是一个开源的 API doc 框架，可以将 Controller 的方法以文档的形式展现。
  • 首先，非常感谢社区让我有动力参与这个项目。在这个版本中，在代码、注释、bug报告方面有一些非常惊人的贡献，看到人们在问题论坛上跳槽来解决问题，我感到很谦卑。它确实激励我克服“困难”，开始认真地工作。有什么更好的办法来摆脱科维德的忧郁！
  • 注意：这是一个突破性的变更版本，我们已经尽可能地保持与springfox早期版本的向后兼容性。在2.9之前被弃用的api已经被积极地删除，并且标记了将在不久的将来消失的新api。所以请注意这些，并报告任何遗漏的内容。

新特性：

  • Remove explicit dependencies on springfox-swagger2
  • Remove any @EnableSwagger2… annotations
  • Add the springfox-boot-starter dependency
  • Springfox 3.x removes dependencies on guava and other 3rd party libraries (not zero dep yet! depends on spring plugin and open api libraries for annotations and models) so if you used guava predicates/functions those will need to transition to java 8 function interfaces.

此版本的亮点：

  • Spring5，Webflux支持（仅支持请求映射，尚不支持功能端点）。
  • Spring Integration支持（非常感谢反馈）。
  • SpringBoot支持springfox Boot starter依赖性（零配置、自动配置支持）。
  • 具有自动完成功能的文档化配置属性。
  • 更好的规范兼容性与2.0。
  • 支持OpenApi 3.0.3。
  • 零依赖。几乎只需要spring-plugin，swagger-core ，现有的swagger2注释将继续工作并丰富openapi3.0规范。

兼容性说明：

  • 需要Java 8
  • 需要Spring5.x（未在早期版本中测试）
  • 需要SpringBoot 2.2+（未在早期版本中测试）

注意：

应用主类增加注解@EnableOpenApi，删除之前版本的SwaggerConfig.java。

启动项目，访问地址：http://localhost:8080/swagger-ui/index.html，注意2.x版本中访问的地址的为http://localhost:8080/swagger-ui.html

整合使用

Maven项目中引入springfox-boot-starter依赖：


????io.springfox
????springfox-boot-starter
????3.0.0

12345

application.yml配置

spring:
??application:
????name:?springfox-swagger
server:
??port:?8080

#?=====?自定义swagger配置?=====?#
swagger:
??enable:?true
??application-name:?${spring.application.name}
??application-version:?1.0
??application-description:?springfox?swagger?3.0整合Demo
??try-host:?http://localhost:${server.port}
12345678910111213

使用@EnableOpenApi注解，启用swagger配置

@EnableOpenApi
@Configuration
public?class?SwaggerConfiguration?{

}
12345

自定义swagger配置类SwaggerProperties

@Component
@ConfigurationProperties("swagger")
public?class?SwaggerProperties?{
????/**
?????*?是否开启swagger，生产环境一般关闭，所以这里定义一个变量
?????*/
????private?Boolean?enable;

????/**
?????*?项目应用名
?????*/
????private?String?applicationName;

????/**
?????*?项目版本信息
?????*/
????private?String?applicationVersion;

????/**
?????*?项目描述信息
?????*/
????private?String?applicationDescription;

????/**
?????*?接口调试地址
?????*/
????private?String?tryHost;

????public?Boolean?getEnable()?{
????????return?enable;
????}

????public?void?setEnable(Boolean?enable)?{
????????this.enable?=?enable;
????}

????public?String?getApplicationName()?{
????????return?applicationName;
????}

????public?void?setApplicationName(String?applicationName)?{
????????this.applicationName?=?applicationName;
????}

????public?String?getApplicationVersion()?{
????????return?applicationVersion;
????}

????public?void?setApplicationVersion(String?applicationVersion)?{
????????this.applicationVersion?=?applicationVersion;
????}

????public?String?getApplicationDescription()?{
????????return?applicationDescription;
????}

????public?void?setApplicationDescription(String?applicationDescription)?{
????????this.applicationDescription?=?applicationDescription;
????}

????public?String?getTryHost()?{
????????return?tryHost;
????}

????public?void?setTryHost(String?tryHost)?{
????????this.tryHost?=?tryHost;
????}
}
1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768

一个完整详细的springfox swagger配置示例：

import?io.swagger.models.auth.In;
import?org.apache.commons.lang3.reflect.FieldUtils;
import?org.springframework.boot.SpringBootVersion;
import?org.springframework.context.annotation.Bean;
import?org.springframework.context.annotation.Configuration;
import?org.springframework.util.ReflectionUtils;
import?org.springframework.web.servlet.config.annotation.InterceptorRegistration;
import?org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import?org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import?springfox.documentation.builders.ApiInfoBuilder;
import?springfox.documentation.builders.PathSelectors;
import?springfox.documentation.builders.RequestHandlerSelectors;
import?springfox.documentation.oas.annotations.EnableOpenApi;
import?springfox.documentation.service.*;
import?springfox.documentation.spi.DocumentationType;
import?springfox.documentation.spi.service.contexts.SecurityContext;
import?springfox.documentation.spring.web.plugins.Docket;

import?java.lang.reflect.Field;
import?java.util.*;

@EnableOpenApi
@Configuration
public?class?SwaggerConfiguration?implements?WebMvcConfigurer?{
????private?final?SwaggerProperties?swaggerProperties;

????public?SwaggerConfiguration(SwaggerProperties?swaggerProperties)?{
????????this.swaggerProperties?=?swaggerProperties;
????}

????@Bean
????public?Docket?createRestApi()?{
????????return?new?Docket(DocumentationType.OAS_30).pathMapping("/")

????????????????//?定义是否开启swagger，false为关闭，可以通过变量控制
????????????????.enable(swaggerProperties.getEnable())

????????????????//?将api的元信息设置为包含在json ResourceListing响应中。
????????????????.apiInfo(apiInfo())

????????????????//?接口调试地址
????????????????.host(swaggerProperties.getTryHost())

????????????????//?选择哪些接口作为swagger的doc发布
????????????????.select()
????????????????.apis(RequestHandlerSelectors.any())
????????????????.paths(PathSelectors.any())
????????????????.build()

????????????????//?支持的通讯协议集合
????????????????.protocols(newHashSet("https",?"http"))

????????????????//?授权信息设置，必要的header?token等认证信息
????????????????.securitySchemes(securitySchemes())

????????????????//?授权信息全局应用
????????????????.securityContexts(securityContexts());
????}

????/**
?????*?API?页面上半部分展示信息
?????*/
????private?ApiInfo?apiInfo()?{
????????return?new?ApiInfoBuilder().title(swaggerProperties.getApplicationName()?+?"?Api?Doc")
????????????????.description(swaggerProperties.getApplicationDescription())
????????????????.contact(new?Contact("lighter",?null,?"123456@gmail.com"))
????????????????.version("Application?Version:?"?+?swaggerProperties.getApplicationVersion()?+?",?Spring?Boot?Version:?"?+?SpringBootVersion.getVersion())
????????????????.build();
????}

????/**
?????*?设置授权信息
?????*/
????private?List?securitySchemes()?{
????????ApiKey?apiKey?=?new?ApiKey("BASE_TOKEN",?"token",?In.HEADER.toValue());
????????return?Collections.singletonList(apiKey);
????}

????/**
?????*?授权信息全局应用
?????*/
????private?List?securityContexts()?{
????????return?Collections.singletonList(
????????????????SecurityContext.builder()
????????????????????????.securityReferences(Collections.singletonList(new?SecurityReference("BASE_TOKEN",?new?AuthorizationScope[]{new?AuthorizationScope("global",?"")})))
????????????????????????.build()
????????);
????}

????@SafeVarargs
????private?final??Set?newHashSet(T...?ts)?{
????????if?(ts.length?>?0)?{
????????????return?new?LinkedHashSet<>(Arrays.asList(ts));
????????}
????????return?null;
????}

????/**
?????*?通用拦截器排除swagger设置，所有拦截器都会自动加swagger相关的资源排除信息
?????*/
????@SuppressWarnings("unchecked")
????@Override
????public?void?addInterceptors(InterceptorRegistry?registry)?{
????????try?{
????????????Field?registrationsField?=?FieldUtils.getField(InterceptorRegistry.class,?"registrations",?true);
????????????List?registrations?=?(List)?ReflectionUtils.getField(registrationsField,?registry);
????????????if?(registrations?!=?null)?{
????????????????for?(InterceptorRegistration?interceptorRegistration?:?registrations)?{
????????????????????interceptorRegistration
????????????????????????????.excludePathPatterns("/swagger**/**")
????????????????????????????.excludePathPatterns("/webjars/**")
????????????????????????????.excludePathPatterns("/v3/**")
????????????????????????????.excludePathPatterns("/doc.html");
????????????????}
????????????}
????????}?catch?(Exception?e)?{
????????????e.printStackTrace();
????????}
????}

}
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121

一些常用注解说明

  • @Api：用在controller类，描述API接口
  • @ApiOperation：描述接口方法
  • @ApiModel：描述对象
  • @ApiModelProperty：描述对象属性
  • @ApiImplicitParams：描述接口参数
  • @ApiResponses：描述接口响应
  • @ApiIgnore：忽略接口方法

示例

项目Demo：springfox-swagger

效果图：

相关推荐

HR必备Excel函数:4个与日期相关的计算函数。

提到日期函数，很多人首先会想到“today”，它可以显示当天的日期，并且每次打开表格时都会自动更新。但是，对于前天、昨天、明天和后天的日期，就不能用yesterday或者tomorrow等这些英文了，...

这篇文章有点长，但可以让你十分钟玩转Excel的时间函数

日期与时间函数——TODAY、NOW、YEAR、MONTH、DAY！如何用WORKDAY函数查询距离某天的第20个工作日是哪一天？如何用NETWORKDAYS函数查询员工工作了多少个工作日？如何用WE...

Excel2020年日历套装，表格设计，农历显示，查阅套打轻松应用

Hello大家好，我是帮帮。今天跟大家分享一组Excel2020年日历套装，表格设计，自带农历控件，查阅套打轻松应用。有个好消息！为了方便大家更快的掌握技巧，寻找捷径。请大家点击文章末尾的“了解更多”...

巧用NETWORKDAYS函数计算两个日期之间工作日的天数

带有日期的单元格是我们日常使用EXCEL的时候经常见到的，有的时候我们需要求出两个日期之间间隔的天数，可以直接用结束日期减去开始日期即可，这是个非常简单的减法公式。不过这个单纯的减法公式会默认去掉开始...

Excel按工作日、休息日进行汇总

1、按周六日/其它时间汇总为了区分一周的周六日和其它时间，可以使用WEEKDAY函数，把WEEKDAY函数的第2个参数指定为2，如WEEKDAY(A3,2)，则周一返回1，周二返回2，…，周六返回...

如何计算每月应出勤天数，如有法定假期和调休，如何计算

本文介绍如何计算每月的应出勤天数。第一部分介绍正常双休制下计算应出勤天数；第二部份介绍当月有法定假期和调休的情况下计算应出勤天数。一、计算正常双休制的应出勤天数如下图所示，要求计算各员工2021年3月...

《Excel一键生成工作日历:让会议排期更轻松!》

每当需要安排会议时，总要翻看日历确认工作日，再逐个标注会议时间，既耗时又容易出错。今天教大家用Excel快速生成工作日历表，让会议排期变得简单高效！一、快速生成日历框架创建基础日期：在A1单元格输入月...

如何计算指定日期区间内，有多少工作日和休息日?

大家好，今天咱们要解决的问题是如何计算给定的一段日期内，正常工作日有多少天，放假时间有多少天？比如咱们要计算2025年3月份工作日一共有多少天，又有多少天放假，如下图所示：通过肉眼我们可以数清楚，20...

如何如何在表格中自动突出显示双休日?

现在不少人喜欢用Excel来制作备忘录或安排工作事项。在表格中输入日期后，可以使用条件格式突出显示双休日，避免在休息日安排了工作。具体方法是这样的：第1步：选择要设置条件格式的日期单元格区域；在“开始...

excel函数技巧:networkdays.intl判断节假日

如图，想知道6月的每一天是否是节假日，公式如下：=NETWORKDAYS.INTL(A2,A2,1,$E$2:$E$28)这个函数既可以判断当前日期（一参=二参）是否是周末及工作日（三参、四参）还可得...

仅需3步，让考勤表根据实际休息日，自动地填充颜色

Hello，大家好，之前跟大家分享了我们如何让考勤表根据单休与双休自动的填充颜色，最近有粉丝问到：能不能让考勤表根据实际的休息日自动的填充颜色呢？可以是可以，只不过因为牵扯到假期调休，我们每年的休息日...

5步搞定动态考勤表!标记节假日、调休日?Excel自动变色!

今天教你用「动态考勤表」一招解决所有问题！只需输入月份，自动变色、自动更新节假日，从此告别加班，效率翻倍！动态考勤表的优势：自动变色：节假日、双休日一键标记，颜色分明。一表多用：修改月份即可...

一起用python做个炫酷音乐播放器，想听啥随便搜

前言前段时间写的Python自制一款炫酷音乐播放器，有不少小伙伴私信我，对播放器提了不少改进建议，让我完善播放器的功能。今天音乐播放器2.0版本完成了，大家一起来看看是如何用python自制一款炫酷的...

用Python做个“冰墩墩雪容融”桌面部件(好玩又有趣)

桌面太单调？今天就带大家，一起用Python的PyQt5开发一个有趣的自定义桌面动画挂件，看看实现的动画挂件效果！下面，我们开始介绍这个自定义桌面动画挂件的制作过程。一、核心功能设计实现将动态图gif...

Python串口调试助手源码分享

以下是一个基于Python和PyQt5实现的串口调试助手示例，包含核心功能实现代码：pythonimportsysimportserialfromPyQt5.QtCoreimportQTim...

一周热门
最近发表
标签列表