四川城乡和住房建设厅网站,wordpress主题制作工具,网站正在建设中动画,广州市招投标交易中心背景
网上集成 swagger 很多都是 Springfox 那个版本的#xff0c;但是那个版本已经不更新了#xff0c;springboot3 集成会报错 Typejavax.servlet.http.HttpServletRequest not present#xff0c;我尝试了很多才知道现在用 Springdoc 了#xff0c;今天我们来入门一下 …背景
网上集成 swagger 很多都是 Springfox 那个版本的但是那个版本已经不更新了springboot3 集成会报错 Typejavax.servlet.http.HttpServletRequest not present我尝试了很多才知道现在用 Springdoc 了今天我们来入门一下
名词解释
提起 api 文档一般都能想起 swagger但是除了 swagger你可能还听说过OpenAPI、Springfox、Springdoc这些和 swagger 又有什么关系呢
OpenAPI
官网 是一个组织OpenAPI Initiative他们指定了一个如何描述HTTP API的规范OpenAPI Specification。既然是规范那么谁想实现都可以只要符合规范即可。
Swagger
官网 它是SmartBear这个公司的一个开源项目里面提供了一系列工具包括著名的 swagger-ui。swagger是早于OpenApi的某一天swagger将自己的API设计贡献给了OpenApi然后由其标准化了。
Springfox
官网 是Spring生态的一个开源库是Swagger与OpenApi规范的具体实现。我们使用它就可以在spring中生成API文档。以前基本上是行业标准目前最新版本可以支持 Swagger2, Swagger3 以及 OpenAPI3 三种格式。但是其从 2020年7月14号就不再更新了不支持springboot3所以业界都在不断的转向我们今天要谈论的另一个库Springdoc新项目就不要用了。
Springdoc
官网 算是后起之秀带着继任Springfox的使命而来。其支持OpenApi规范支持Springboot3我们的新项目都应该使用这个。
总结
Swagger 和 OpenAPI 是一对相关的概念Swagger 是前身OpenAPI 是其演进和规范化。
Springfox和 Springdoc 是一对相关的概念 Springfox是一个将 Swagger 2.x 规范集成到 Spring Boot 项目中的库提供了用于定义 API 和生成 Swagger UI 的功能。 Springdoc 是一个将 OpenAPI 3.x 规范集成到 Spring Boot 项目中的库提供了用于定义 API 和生成 Swagger UI 的功能使用原生的 Spring 5 注解。
如果你使用的是 Swagger 2.x可以选择 Springfox 如果你使用的是 OpenAPI 3.x可以选择 Springdoc。
Springdoc简单示例
1、引入依赖
dependencygroupIdorg.springdoc/groupIdartifactIdspringdoc-openapi-starter-webmvc-ui/artifactIdversion2.2.0/version
/dependency2、设置好端口号也就是你项目的端口号 application.properties
server.port90903、浏览器访问 http://localhost:9090/swagger-ui/index.html 或者访问 http://localhost:9090/swagger-ui.html 也会重定向到 http://localhost:9090/swagger-ui/index.html 这里默认配置是这个所以才可以重定向 springdoc.swagger-ui.path/swagger-ui.html是不是超简单接下来看看还有什么其他的配置
其他配置示例
接下来我简单写一个配置大家看看映射到界面是哪里。 1、创建配置类 config/SpringDocConfig.java
package com.zhangyu.config;import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;Configuration
public class SpringDocConfig {Beanpublic OpenAPI springShopOpenAPI() {return new OpenAPI().info(new Info().title(Lvan的Swagger).description(这是一个springboot测试).version(v1.0.0).license(new License().name(Apache 2.0).url(http://springdoc.org))).externalDocs(new ExternalDocumentation().description(Lvan的博客).url(https://blog.csdn.net/weixin_43972437));}
}2、在控制器上加一些注解 主要是下面的 Tag、Operation 注解
package com.zhangyu.controller;import com.zhangyu.mapper.UserMapper;
import com.zhangyu.model.UserForJpa;
import com.zhangyu.model.UserForMybatis;
import com.zhangyu.repository.UserRepository;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;import java.util.List;RestController
RequestMapping(/users)
Tag(name 用户模块, description 用户模块的描述)
public class UserController {Autowiredprivate UserRepository userRepository;Autowiredprivate UserMapper userMapper;GetMapping(getAllForJpa)Operation(summary 获取用户信息-jpa方式, description 以jpa的方式获取用户)public ListUserForJpa getAllUsersForJpa() {return userRepository.findAll();}GetMapping(getAllForMybatis)Operation(summary 获取用户信息-Mybatis方式, description 以Mybatis的方式获取用户)public ListUserForMybatis getAllUsersForMybatis() {return userMapper.findAll();}
} 总结
看到这里基本也就入门了其他想要的配置就去官方文档里面找吧
