神器 SpringDoc 横空出世！最适合 SpringBoot 的API文档工具来了

在使用SpringBoot中配置Swagger2的时候，出现

Unable to infer base url This is common when using dynamic servlet registration or when the API is behind an API Gateway The base url is the root of where all the swagger resources are served For eg if the api is available at >

在这篇博客中，会记录 springfox3 的基本配置与使用；由于swagger-ui看得不是很习惯，额外引入了 knife4j ，使用增强版本的swagger的前端ui。

注意

@ConditionalOnProperty 注解声明了当 springfoxdocumentationenabled 为 true 时启用配置，而且默认值就是 true （Swagger仅仅建议在开发阶段使用）；

这里以 WebMvcConfig 为例。

@ApiImplicitParam

用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

name：参数名

value：参数的汉字说明、解释

required：参数是否必须传

paramType：参数放在哪个地方

· header --> 请求参数的获取：@RequestHeader

· query --> 请求参数的获取：@RequestParam

· path（用于restful接口）--> 请求参数的获取：@PathVariable

· body（不常用）

· form（不常用）

dataType：参数类型，默认String，其它值dataType="Integer"

defaultValue：参数的默认值

swagger页面：项目地址 + /swagger-ui/indexhtml

knife4j页面：项目地址 + /dochtml

1 swagger3中，设置全局参数不生效

Github : >

重命名

swagger: 20

openAPI: 300

Swagger 20 基础URL结构

OpenAPI 30 基础URL结构

我们可以定义一个基础url，通过{}里面装载变量值（类似于路径模版），在使用时，通过variables属性可以定义变量值，当然也可以给定默认值

Swagger 2中的definitions概念在OpenAPI 3中标准化为组件，可以在多个地方重复使用且可定义，组件列表如下：

Swagger 2

Swagger 2最容易混淆的方面之一是body / formData。它们是参数的子集，只能有一个或另一个，如果你使用body，格式与参数的其余部分不同（只能使用body参数，名称不相关，格式不同，等等）

OpenAPI 3

现在，body已经被移入了它自己的叫做requestBody的部分，并且formData也已经被合并到里面。另外，cookies已经被添加为参数类型（除了现有的标题，路径和查询选项之外）。

requestBody有很多新的功能。现在可以提供example（或数组examples）for requestBody。这是非常灵活的（你可以传入一个完整的例子，一个参考，甚至是一个URL的例子）。

新的requestBody支持不同的媒体类型（content是一个MIME_Types的数组，像application/json或者text/plain，当然你也可以用 / 捕捉所有）。

对于参数，你有两个选择你想如何定义它们。你可以定义一个“模式”（像原来20那样），可以尽情地描述项目。如果更复杂，可以使用“requestBody”中的“content”。

通配符的出现，我们可以以“4XX”来定义响应，而不必单独定义每个响应码。

响应和响应头可以更复杂。可以使用“content”对象（如在请求中）的有效载荷。

链接是OpenAPI 3最有趣的补充之一。它有点复杂，但可能非常强大。这基本上是描述“下一步是什么”的一种方式。

比方说，你得到一个用户，它有一个addressId。这addressId本身是无用的。您可以使用链接来展示如何“扩大”，并获得完整的地址。

在“/ users / {userId}”的响应中，我们找回了一个addressId。“链接”描述了如何通过引用“$ responsebody＃/ addressId”来获取地址。

另一个用例是分页。如果要获取100个结果，links可以显示如何获得结果101-200。它是灵活的，这意味着它可以处理任何分页方案limits来cursors。

Swagger 2

OpeanAPI 3

一堆安全性的变化！它已被重命名，OAuth2流名已更新，您可以有多个流，并且支持OpenID Connect。“基本”类型已被重命名为“>

一个好的 API's，必然离不开一个好的API文档

要开发纯手写 API 文档，不存在的 :=)

项目地址：>

以上就是关于神器 SpringDoc 横空出世！最适合 SpringBoot 的API文档工具来了全部的内容，包括:神器 SpringDoc 横空出世！最适合 SpringBoot 的API文档工具来了、springboot,springmvc整合swagger、SpringBoot使用Swagger2出现Unable to infer base url.等相关内容解答，如果想了解更多相关内容，可以关注我们，你们的支持是我们更新的动力！