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

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

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

  • 资料
  • 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

效果图：

相关推荐

python入门到脱坑函数—定义函数_如何定义函数python

Python函数定义：从入门到精通一、函数的基本概念函数是组织好的、可重复使用的代码块，用于执行特定任务。在Python中，函数可以提高代码的模块性和重复利用率。二、定义函数的基本语法def函数名(...

javascript函数的call、apply和bind的原理及作用详解

javascript函数的call、apply和bind本质是用来实现继承的，专业点说法就是改变函数体内部this的指向，当一个对象没有某个功能时，就可以用这3个来从有相关功能的对象里借用过来...

JS中 call()、apply()、bind() 的用法

其实是一个很简单的东西，认真看十分钟就从一脸懵B到完全理解！先看明白下面：例1obj.objAge;//17obj.myFun()//小张年龄undefined例2shows(...

Pandas每日函数学习之apply函数_apply函数python

apply函数是Pandas中的一个非常强大的工具，它允许你对DataFrame或Series中的数据应用一个函数，可以是自定义的函数，也可以是内置的函数。apply可以作用于DataF...

Win10搜索不习惯 换个设定就好了_window10搜索用不了怎么办

Windows10的搜索功能是真的方便，这点用惯了Windows10的小伙伴应该都知道，不过它有个小问题，就是Windows10虽然会自动联网搜索，但默认使用微软自家的Bing搜索引擎和Edge...

面试秘籍:call、bind、apply的区别,面试官为什么总爱问这三位?

引言你有没有发现，每次JavaScript面试，面试官总爱问你call、bind和apply的区别？好像这三个方法成了通关密码，掌握了它们，就能顺利过关。其实不难理解，面试官问这些问题，不...

记住这8招，帮你掌握“追拍“摄影技法—摄影早自习第422日

杨海英同学提问：请问叶梓老师，我练习追拍时，总也不能把运动的人物拍清晰，速度一般掌握在1/40-1/60，请问您如何把追拍拍的清晰？这跟不同的运动形式有关系吗？请您给讲讲要点，谢谢您！摄影：Damia...

[Sony] 有点残酷的测试A7RII PK FS7

都是好机！手中利器！主要是最近天天研究fs5，想知道fs5与a7rii后期匹配问题，苦等朋友的fs5月底到货，于是先拿手里现有的fs7小测一下，十九八九也能看到fs5的影子，另外也了解一下fs5k标配...

AndroidStudio_Android使用OkHttp发起Http请求

这个okHttp的使用,其实网络上有很多的案例的,但是,如果以前没用过,copy别人的直接用的话,可以发现要么导包导不进来,要么,人家给的代码也不完整,这里自己整理一下.1.引入OkHttp的jar...

ESL-通过事件控制FreeSWITCH_es事务控制

通过事件提供的最底层控制机制，允许我们有效地利用工具箱，适时选择使用其中的单个工具。FreeSWITCH是一个核心交换与混合矩阵，它周围有几十个模块提供各种功能特性。我们完全控制了所有的即时信息，这些...

【调试】perf和火焰图_perf生成火焰图

简介perf是linux上的性能分析工具，perf可以对event进行统计得到event的发生次数，或者对event进行采样，得到每次event发生时的相关数据(cpu、进程id、运行栈等)，利用这些...

文本检索控件也玩安卓?dtSearch Engine发布Android测试版

dtSearchEngineforLinux（原生64-bit/32-bitC++和JavaAPIs）和dtSearchEngineforWin&.NET（原生64-bi...

网站后台莫名增加N个管理员，记一次SQL注入攻击

网站没流量，但却经常被SQL注入光顾。最近，网站真的很奇怪，网站后台不光莫名多了很多“管理员”，所有的Wordpres插件还会被自动暂停，导致一些插件支持的页面，如WooCommerce无法正常访问、...

多元回归树分析Multivariate Regression Trees，MRT

多元回归树（MultivariateRegressionTrees，MRT）是单元回归树的拓展，是一种对一系列连续型变量递归划分成多个类群的聚类方法，是在决策树(decision-trees)基础...

JMETER性能测试_JMETER性能测试指标

jmeter为性能测试提供了一下特色：jmeter可以对测试静态资源（例如js、html等）以及动态资源（例如php、jsp、ajax等等）进行性能测试jmeter可以挖掘出系统最大能处...

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