如何在 Swagger UI 的标记中插入小的自定义? [英] How to insert minor customization into Swagger UI inside its markup?
问题描述
我有一个使用 Swashbuckle(Swashbuckle.AspNetCore.SwaggerGen 3.0.0 和 Swashbuckle.AspNetCore.SwaggerUi 3.0.0)记录的 .NET Core 项目.我的目标是在带有 title 类的 DIV 正下方添加一个自定义标签(即在服务名称下方但在端点上方).
I have a .NET Core project documented using Swashbuckle (Swashbuckle.AspNetCore.SwaggerGen 3.0.0 and Swashbuckle.AspNetCore.SwaggerUi 3.0.0). My aim's to add a custom tag right below the DIV with class title (i.e. below the service's name but above the endpoints).
当我调查 Swagger UI 标记时，我看到有一个带有 swagger-ui 类的 DIV，我想将我的东西插入其中，可以这么说.我今天的设置是一个名为 donkey.html 的文件，当我访问 Swagger UI 的 URL 时会呈现该文件，如下所示.
When I investigate Swagger UI markup, I see there's a DIV with class swagger-ui and I'd like insert my stuff into it, so to speak. The setup I have today is a file called donkey.html which is being rendered when I access the URL of Swagger UI looking as follows.
...
<body>
<div id="swagger-ui"></div>
<div id="api_info"></div>
<!-- ... -->
<script src="./swagger-ui-bundle.js"></script>
<script src="./swagger-ui-standalone-preset.js"></script>
<script type="text/javascript">
(function () { ... })();
</script>
</body>
</html>
我已经在谷歌上搜索了几个小时，并阅读了很多关于 OpenAPI 和 YAML 的内容.然而，我得到的印象是它需要对 Swagger UI 项目进行全面重建，而我目前的目标是完成一个更简单的任务.
I've googled for a few hours now and read a lot about OpenAPI and YAML among other things. However, the impression I'm getting is that it requires a whole rebuild of the Swagger UI project and my ambition targets a much simpler task at the moment.
有没有办法插入名为 api_info 的 DIV，使其作为 swagger_ui 的一部分呈现，而无需重新生成整个 Swagger UI 项目?
Is there a way to jack the DIV called api_info so it renders as a part of swagger_ui with out regenerating the whole Swagger UI project?
我尝试增加基本布局，如图所示here 但结果很糟糕，结果比我的目标要复杂一些.也许这是创建模块的唯一可行方法，在这种情况下我会考虑它，但在这种情况下这是最后的资源.
I tried to augment onto the base layout as shown here but that ended poorly and turned out to be a bit more complicated than what I'm aiming for. Perhaps it's the only feasible approach to create a module, in which case I'll consider it, but that's the last resource in this case.
推荐答案
Swagger UI 3.x 具有可让您添加或修改 UI 元素的插件系统.可以在以下位置找到有关插件的一些文档:
插件
自定义 SwaggerUI 3.x 的预期方式是什么?
Swagger UI 3.x has the plugin system that lets you add or modify UI elements. Some documentation on plugins can be found at:
Plugins
What's the intended way of customizing SwaggerUI 3.x?
无需重新编译 Swagger UI 即可使用插件，实际上可以直接在 index.html 页面中定义插件.要添加或更改 UI 元素，您需要一个使用 wrapComponents 和 React.createElement 以构建所需的 DOM 结构.(另请参阅React without JSX.)
There is no need to recompile Swagger UI to use plugins, you can actually define the plugins directly in the index.html page. To add or change UI elements, you need a plugin that uses wrapComponents and React.createElement to build the desired DOM structure. (See also React Without JSX.)
要使自定义插件生效，必须将它们添加到 SwaggerUIBundle 构造函数中的 plugins 列表中.
For the custom plugins to have effect, they must be added to the plugins list in the SwaggerUIBundle constructor.
这是一个示例插件，它在 API 标题的上方和下方添加了自定义 标头:
Here is a sample plugin that adds custom <h3> headers above and below the API title:
// index.html
<script>
window.onload = function() {
// Custom plugin that adds extra stuff
const MyCustomPlugin = function() {
return {
wrapComponents: {
// add text above InfoContainer - same effect as above title
InfoContainer: (Original, { React }) => (props) => {
return React.createElement("div", null,
React.createElement("h3", null, "I'm above the InfoContainer"),
React.createElement(Original, props)
)
},
// and/or add text above API description
InfoUrl: (Original, { React }) => (props) => {
return React.createElement("div", null,
React.createElement(Original, props),
React.createElement("h3", null, "I'm above the API description")
)
}
}
}
}
const ui = SwaggerUIBundle({
url: "http://petstore.swagger.io/v2/swagger.json",
dom_id: '#swagger-ui',
...
plugins: [
MyCustomPlugin, // <------ add your custom plugin here
SwaggerUIBundle.plugins.DownloadUrl
],
...
结果如下:
这篇关于如何在 Swagger UI 的标记中插入小的自定义?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
