swagger-ui-react 前端引用草稿
前言
SwaggerUI是一个React组件，它接受一个配置对象作为其唯一的属性。这个配置对象可以包含多个属性来自定义SwaggerUI的行为和外观。以下是SwaggerUI支持的主要属性及其说明：
| 主要属性 | 说明 |
|---|---|
| url： | 指定要显示的Swagger规范文件的URL或本地文件的路径。 |
| spec： | 指定Swagger规范对象，而不是通过URL加载。如果同时提供了url和spec，则spec将覆盖url。 |
| dom_id： | 指定要将SwaggerUI渲染到的DOM元素的ID。 |
| layout： | 指定SwaggerUI的布局配置。可以是默认的“BaseLayout”或您自己定义的自定义布局。 |
| docExpansion： | 指定API文档的初始展开状态。可选值为“none”（默认值）、“list”和“full”。 |
| deepLinking： | 指定是否启用深度链接，使用户可以从当前页面共享特定资源的链接。 |
| requestInterceptor： | 指定用于拦截SwaggerUI中发出的所有请求的函数。 |
| responseInterceptor： | 指定用于拦截SwaggerUI中接收的所有响应的函数。 |
| supportedSubmitMethods： | 指定在SwaggerUI操作中显示哪些HTTP方法（例如GET、POST、PUT等）的数组。 |
| validatorUrl： | 指定用于验证规范的URL或本地文件的路径。 |
| oauth2RedirectUrl： | 指定OAuth2回调URL的URL路径，以便在请求OAuth2令牌时进行重定向。 |
| plugins： | 指定用于SwaggerUI的插件数组。 |
| presets： | 指定要预定义的SwaggerUI配置的名称数组。可以是“SwaggerUIStandalonePreset”、“SwaggerUIBundlePreset”或您自己定义的自定义预设。 |
下面是一个使用swagger-ui-react 4.2.1版本的自定义layout的示例代码
import React, { Component } from "react";
import SwaggerUI from "swagger-ui-react";
import "swagger-ui-react/swagger-ui.css";
class CustomLayout extends Component {
render() {
return (
<div>
<div className="header">
<h1>Custom Header</h1>
</div>
<div className="swagger-container">
<SwaggerUI {...this.props} />
</div>
<div className="footer">
<h1>Custom Footer</h1>
</div>
</div>
);
}
}
class App extends Component {
render() {
return (
<div className="App">
<SwaggerUI
url="https://petstore.swagger.io/v2/swagger.json"
docExpansion="none"
layout={CustomLayout}
/>
</div>
);
}
}
export default App;
在这个示例中，我们创建了一个CustomLayout组件，它将作为SwaggerUI组件的layout属性值传递。在CustomLayout组件中，我们定义了一个自定义的头部和底部，并使用{...this.props}语法将所有传递给CustomLayout组件的属性传递给SwaggerUI组件。
在App组件中，我们将CustomLayout组件传递给SwaggerUI组件的layout属性，以便在SwaggerUI组件中使用自定义的布局。我们还通过url属性指定了要加载的Swagger API文档的URL，以及通过docExpansion属性设置了文档的默认扩展。
发现者何种自定义方式好像不起什么作用！
layout
在Swagger-UI-React中，layout属性可以接受以下几种不同的值：
-
"BaseLayout"：这是Swagger-UI-React的默认布局，它包含API文档的标题、描述和操作列表。
-
"StandaloneLayout"：这个布局只显示操作列表，没有标题或描述。
-
自定义布局组件：你可以创建自己的布局组件，并将其传递给layout属性。这允许你完全自定义Swagger-UI的外观和行为。自定义布局组件应该是一个React组件，它接受以下props：
- basePath: 当前API的基本路径
- getComponent: 获取Swagger-UI组件的函数
- spec: Swagger文档的规范
- fn: Swagger-UI操作的方法
- layoutSelectors: 获取和更新布局状态的函数
- errSelectors: 获取和更新错误状态的函数
-
自定义布局函数：你还可以创建一个函数，该函数接受上述props作为参数，并返回一个React元素。这允许你在不使用自定义布局组件的情况下完全自定义Swagger-UI的外观和行为。
总的来说，Swagger-UI-React的layout属性非常灵活，允许你以多种方式自定义Swagger-UI的外观和行为。
docExpansion
SwaggerUI中的docExpansion属性用于配置API文档的初始展开状态。它控制在SwaggerUI中显示的API文档的呈现方式。
该属性有以下几个可选值：
none: 默认值，所有操作都将被折叠，并且用户需要手动单击每个操作以查看其细节。
list: 将显示所有操作的摘要，并将其分组到其各自的资源中。
full: 将显示所有操作和资源的所有详细信息。
您可以将docExpansion属性传递给SwaggerUI组件的配置对象中，如下所示：
const ui = SwaggerUI({
// ...
docExpansion: 'list', // 将所有操作摘要显示为列表
// ...
});
onComplete
SwaggerUI提供了onComplete回调函数，该函数在文档加载完毕并呈现在UI中后被触发。您可以在该回调函数中获取当前API文档头的信息，以便进行进一步处理。
例如，以下代码演示了如何在onComplete回调函数中获取当前API文档头的信息并将其打印到控制台：
const ui = SwaggerUI({
// ...
onComplete: (swaggerApi, swaggerUi) => {
const currentApi = swaggerUi.getCurrentApi();
console.log(`当前API文档头信息： ${currentApi.info.title} - ${currentApi.info.version}`);
}
});
在这个例子中，swaggerUi.getCurrentApi()方法返回当前显示的Swagger规范对象。您可以从Swagger规范对象中获取各种信息，例如文档标题和版本等。
如果您需要在用户与SwaggerUI交互时获取API文档头的信息，例如当用户单击操作时，您可以使用SwaggerUI提供的事件来注册回调函数。例如，以下代码演示了如何在单击操作时获取当前API文档头的信息并将其打印到控制台：
const ui = SwaggerUI({
// ...
onComplete: (swaggerApi, swaggerUi) => {
// 注册单击操作事件
swaggerUi.getSystem().on('opblock-select', (e) => {
const currentApi = swaggerUi.getCurrentApi();
console.log(`当前API文档头信息： ${currentApi.info.title} - ${currentApi.info.version}`);
});
}
});
在这个例子中，swaggerUi.getSystem().on('opblock-select', callback)方法注册一个事件处理程序，在用户单击操作时被触发。
在事件处理程序中，我们可以使用前面提到的方法来获取当前API文档头的信息。
以下是一个完整的使用SwaggerUI的示例，其中包括使用docExpansion属性自定义API文档的默认展开状态和使用onComplete回调函数获取当前API文档头的信息。
import React, { useState } from 'react';
import SwaggerUI from 'swagger-ui-react';
import 'swagger-ui-react/swagger-ui.css';
function App() {
const [currentApi, setCurrentApi] = useState(null);
const onComplete = (swaggerApi, swaggerUi) => {
const api = swaggerUi.getCurrentApi();
setCurrentApi(api);
};
return (
<div className="App">
{currentApi && (
<h1>
{currentApi.info.title} - {currentApi.info.version}
</h1>
)}
<SwaggerUI
url="https://petstore.swagger.io/v2/swagger.json"
docExpansion="list"
onComplete={onComplete}
/>
</div>
);
}
export default App;
在这个示例中，我们使用useState来存储当前API文档头的信息。
在onComplete回调函数中，我们使用swaggerUi.getCurrentApi()方法获取当前API文档头的信息，并使用setCurrentApi更新状态。
然后，我们根据当前API文档头的信息来渲染一个标题。
最后，我们将url和docExpansion属性传递给SwaggerUI组件，以便呈现Swagger规范文件并自定义API文档的默认展开状态。
