Question

我有一个由Swagger 3（Swashbuckle.AspNetCore.SwaggerGen 3.0.0和Swashbuckle.AspNetCore.SwaggerUi 3.0.0）记录的.NET Core项目。我的目的是在DIV下方添加 title 类的自定义标签（即，在服务名称下方但在端点上方）。

当我研究标记时，我发现有一个类为 swagger-ui 的DIV，可以将我的内容插入其中。我今天设置的是一个名为 donkey.html 的文件，当我访问Swagger的URL时，该文件将呈现如下。

...
<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>

我已经在Google上搜索了几个小时，并且阅读了很多有关OpenAPI和YAML的内容。但是，我得到的印象是，它需要对Swagger项目进行整个重建，而我的目标是将当前的任务简单得多。

是否有一种方法可以插入称为 api_info 的DIV，使其在不重新生成整个Swagger项目的情况下呈现为 swagger_ui 的一部分？

我尝试扩充here所示的基本布局，但是效果很差，结果比我想要的要复杂一些。也许这是创建模块的唯一可行方法，在这种情况下，我将考虑使用它，但这是这种情况下的最后资源。

Answer 1

Swagger UI 3.x具有使您可以添加或修改UI元素的插件系统。有关插件的一些文档可以在以下位置找到：
Plugins
What's the intended way of customizing SwaggerUI 3.x?

无需重新编译Swagger UI即可使用插件，实际上您可以直接在index.html页面上定义插件。要添加或更改UI元素，您需要一个使用wrapComponents和React.createElement的插件来构建所需的DOM结构。（另请参见React Without JSX。）

要使自定义插件生效，必须将它们添加到plugins构造函数的SwaggerUIBundle列表中。

示例

这是一个示例插件，在API标题的上方和下方添加了自定义<h3>头：

// 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 with customized layour

如何在标记中的Swagger中插入次要自定义项？

1 个答案:

示例