北京网站设计公司wx成都柚米科技15,网站外链内链怎么做,仕德伟做的网站,传奇来了网页版使用springdoc-openapi这个库来生成swagger的api文档
官方Github仓库#xff1a; https://github.com/springdoc/springdoc-openapi
官网地址#xff1a;https://springdoc.org 目录题 1. 引入依赖2. 拦截器设置3. 访问接口页面3.1 添加配置项#xff0c;使得访问路径变短…使用springdoc-openapi这个库来生成swagger的api文档
官方Github仓库 https://github.com/springdoc/springdoc-openapi
官网地址https://springdoc.org 目录题 1. 引入依赖2. 拦截器设置3. 访问接口页面3.1 添加配置项使得访问路径变短非必须 4. 修改页面显示信息5. 注解 1. 引入依赖
目前最新的版本是 springdoc-openapi v2.6.0。
然而 springdoc-openapi v1.8.0 是支持 Spring Boot 2.x 和 1.x 的最新开源版本。 而我的项目用的是 springboot 2.2.1 于是我就选择 1.8.0 的版本。
dependencygroupIdorg.springdoc/groupIdartifactIdspringdoc-openapi-ui/artifactIdversion1.8.0/version
/dependency大伙如果用的是 springboot 3 可以尝试使用最新版本的。 注意SpringDoc不兼容swagger2的注解 2. 拦截器设置
如果项目中使用到了拦截器那么就无法访问 http://localhost:8080/swagger-ui.html端口号自行修改
需要到 WebConfigurer 的 addInterceptors 方法中排除swagger的路径
.excludePathPatterns(/swagger**/**,/**/api-docs/**)或者这种写法.excludePathPatterns(/swagger**/**)
.excludePathPatterns(/**/api-docs/**)案例 // 自定义拦截器JwtInterceptor设置拦截规则Overridepublic void addInterceptors(InterceptorRegistry registry) {registry.addInterceptor(loginInterceptor).addPathPatterns(/**).excludePathPatterns(/login, /register, /files/**,/swagger**/**,/**/api-docs/**);}或者这样写 // 自定义拦截器JwtInterceptor设置拦截规则Overridepublic void addInterceptors(InterceptorRegistry registry) {registry.addInterceptor(jwtInterceptor).addPathPatterns(/**).excludePathPatterns(/login).excludePathPatterns(/register).excludePathPatterns(/files/**)// 排除swagger.excludePathPatterns(/swagger**/**).excludePathPatterns(/**/api-docs/**);}3. 访问接口页面
配置好拦截器重新启动访问 http://localhost:8080/swagger-ui.html端口号自行修改
就可以看到如下画面代表可以成功使用swagger了。 通过搜索框可以看到访问路径是被重定向到 http://localhost:8080/v3/api-docs 。
所以排除的路径中把包含swagger和api-docs的路径都排除了。
3.1 添加配置项使得访问路径变短非必须
此时也可以在application.properties中添加一些配置具体可以参考Spring Boot 整合 springdoc-openapi中的配置。
只加一行把/swagger-ui.html这个默认路径修改成比较方便访问的路径。
springdoc.swagger-ui.path/api-docs这样就变成了可以用 http://localhost:8080/api-docs 较短的路径来访问了。
4. 修改页面显示信息
基本信息注解描述可用于属性OpenAPIDefinition定义整个 API 文档的基本信息类、接口info指定 Info 注解的对象用于描述 API 文档的基本信息。Info定义 API 文档的基本信息类、接口titleAPI 的标题。descriptionAPI 的描述。versionAPI 的版本号。termsOfService服务条款的 URL。contact指定 Contact 注解的对象用于描述联系人信息。license指定 License 注解的对象用于描述许可证信息。Contact定义 API 文档中的联系人信息类、接口name联系人的名称。url联系人的网址。email联系人的电子邮件地址。License定义 API 文档中的许可证信息类、接口name许可证的名称。url许可证的网址。externalDocs定义 API 文档中的额外信息类、接口description信息的描述。url信息的网址。
同样是在WebConfigurer中配置添加如下代码 Beanpublic OpenAPI openAPI(Value(${springdoc.version}) String appVersion) {return new OpenAPI().info(new Info() // ## API的基本信息包括标题、版本号、描述、联系人等.title(博客论坛系统 API) // Api接口文档标题必填.description(博客论坛系统 前台用户和后台管理 API) // Api接口文档描述.version(appVersion) // Api接口版本.license(new License() // ## 联系人信息.name(Apache2.0) // 授权名称.url(http://springdoc.org)) // 授权信息).contact(new Contact() // ## 作者信息.name(奇妙方程式) // 作者名称.email(229600398qq.com) // 作者邮箱.url(https://blog.csdn.net/weixin_45940369) // 介绍作者的URL地址).externalDocs(new ExternalDocumentation() // ## API的额外信息.description(文档) // 描述.url(https://blog.csdn.net/weixin_45940369/article/details/141058944)); // 链接}这里配置了一个自定义的配置参数springdoc.version也可以直接写成1.0所以需要把这个加到application.properties中
springdoc.version1.0重新启动查看页面 5. 注解
swagger2 和 swagger3 的注解的区别
用途swagger2swagger3注解位置案例给 API 分组ApiTag(name)Controller类上Tag(name “活动管理”)描述 API 的操作ApiOperationOperation(summary)Controller方法上Operation(summary “新增活动接口”, description “新增活动接口的说明”)描述操作的输入参数ApiImplicitParamsParametersController方法上描述操作的输入参数ApiImplicitParamParameter(description)Controller方法上描述操作的输入参数ApiParamParameter(description)Controller方法参数类上描述操作的输入参数ApiIgnoreParameter(hiddentrue) 或 Operation(hiddentrue) 或 Hidden类或方法或参数上描述数据模型的属性ApiModelSchema实体类上Schema(title“活动对象”, description“活动对象的全部字段属性”)描述数据模型的属性ApiModelPropertySchema实体类属性上Schema(description “活动id”, requiredMode Schema.RequiredMode.REQUIRED, example “1”)
title、name名称description描述requiredMode指定该属性的必需性 Schema.RequiredMode.REQUIRED 表示这个属性是必需example提供该属性的示例值 展示该属性的一个具体示例 参考文章 https://www.cnblogs.com/antLaddie/p/17418078.html https://www.cnblogs.com/strongmore/p/18106597 https://www.jianshu.com/p/0c09b675c2d3 https://blog.csdn.net/weixin_59383491/article/details/135105646
