跳到内容

插件点

Swagger UI 通过插件系统公开其大部分内部逻辑。

通常，覆盖核心内部构件以实现自定义行为是有益的。

注意：语义版本控制

Swagger UI 的内部 API 不是我们公共契约的一部分，这意味着它们可能会在没有主版本更改的情况下发生变化。

如果您的自定义插件包装、扩展、覆盖或使用任何内部核心 API，我们建议您在应用程序中指定要使用的 Swagger UI 的特定次要版本，因为它们在补丁版本之间不会更改。

例如，如果您通过 NPM 安装 Swagger UI，您可以使用波浪号来执行此操作

1
{
2
  "dependencies": {
3
    "swagger-ui": "~3.11.0"
4
  }
5
}

fn.opsFilter

使用 filter 选项时，标签名称将按用户提供的值进行筛选。如果您想自定义此行为，可以覆盖默认的 opsFilter 函数。

例如，您可以实现多短语筛选器

1
const MultiplePhraseFilterPlugin = function() {
2
  return {
3
    fn: {
4
      opsFilter: (taggedOps, phrase) => {
5
        const phrases = phrase.split(", ")
6


7
        return taggedOps.filter((val, key) => {
8
          return phrases.some(item => key.indexOf(item) > -1)
9
        })
10
      }
11
    }
12
  }
13
}

Logo 组件

在使用独立预设时，SwaggerUI 徽标会在顶部栏中呈现。可以通过插件 API 替换 Logo 组件来交换徽标

1
import React from "react";
2
const MyLogoPlugin = {
3
  components: {
4
    Logo: () => (
5
      <img alt="My Logo" height="40" src="data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iNTM3IiBoZWlnaHQ9IjEzNCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KCiA8Zz4KICA8dGl0bGU+TGF5ZXIgMTwvdGl0bGU+CiAgPHRleHQgdHJhbnNmb3JtPSJtYXRyaXgoMy40Nzc2OSAwIDAgMy4yNjA2NyAtNjczLjEyOCAtNjkxLjk5MykiIHN0cm9rZT0iIzAwMCIgZm9udC1zdHlsZT0ibm9ybWFsIiBmb250LXdlaWdodD0ibm9ybWFsIiB4bWw6c3BhY2U9InByZXNlcnZlIiB0ZXh0LWFuY2hvcj0ic3RhcnQiIGZvbnQtZmFtaWx5PSInT3BlbiBTYW5zIEV4dHJhQm9sZCciIGZvbnQtc2l6ZT0iMjQiIGlkPSJzdmdfMSIgeT0iMjQxLjIyMTkyIiB4PSIxOTYuOTY5MjEiIHN0cm9rZS13aWR0aD0iMCIgZmlsbD0iIzYyYTAzZiI+TXkgTG9nbzwvdGV4dD4KICA8cGF0aCBpZD0ic3ZnXzIiIGQ9Im0zOTUuNjAyNSw1MS4xODM1OWw1My44Nzc3MSwwbDE2LjY0ODYzLC01MS4xODM1OGwxNi42NDg2NCw1MS4xODM1OGw1My44Nzc3LDBsLTQzLjU4NzksMzEuNjMyODNsMTYuNjQ5NDksNTEuMTgzNThsLTQzLjU4NzkyLC0zMS42MzM2OWwtNDMuNTg3OTEsMzEuNjMzNjlsMTYuNjQ5NDksLTUxLjE4MzU4bC00My41ODc5MiwtMzEuNjMyODN6IiBzdHJva2Utd2lkdGg9IjAiIHN0cm9rZT0iIzAwMCIgZmlsbD0iIzYyYTAzZiIvPgogPC9nPgo8L3N2Zz4="/>
6
    )
7
  }
8
}

JSON Schema 组件

在 swagger 中，有所谓的 JSON Schema 组件。这些组件用于使用 application/x-www-form-urlencoded 或 multipart/* 媒体类型呈现参数和请求正文组件的输入。

在内部，swagger 使用以下映射从 OpenAPI 规范架构信息中查找 JSON Schema 组件

对于每个架构的类型（例如，string、array、…）以及如果定义的架构格式（例如，'date'、'uuid'、…），都有一个相应的组件映射

如果定义了格式

1
`JsonSchema_${type}_${format}`

如果 JsonSchema_${type}_${format} 组件不存在或未定义格式，则回退

1
`JsonSchema_${type}`

默认

1
`JsonSchema_string`

通过此方法，可以定义自定义输入组件或覆盖现有组件。

示例日期选择器插件

如果要输入日期值，您可以提供一个自定义插件，将 react-datepicker 集成到 swagger-ui 中。您只需创建一个组件，根据格式相应地包装 react-datepicker 即可。

有两种情况

  • 1
    type: string
    2
    format: date
    成功映射的最终名称：JsonSchema_string_date
  • 1
    type: string
    2
    format: date-time
    成功映射的最终名称：JsonSchema_string_date-time

这需要两个组件，以及一些简单的逻辑，用于在格式为日期时去除任何时间输入

1
import React from "react";
2
import DatePicker from "react-datepicker";
3
import "react-datepicker/dist/react-datepicker.css";
4


5
const JsonSchema_string_date = (props) => {
6
  const dateNumber = Date.parse(props.value);
7
  const date = dateNumber
8
    ? new Date(dateNumber)
9
    : new Date();
10


11
  return (
12
    <DatePicker
13
      selected={date}
14
      onChange={d => props.onChange(d.toISOString().substring(0, 10))}
15
    />
16
  );
17
}
18


19
const JsonSchema_string_date_time = (props) => {
20
  const dateNumber = Date.parse(props.value);
21
  const date = dateNumber
22
    ? new Date(dateNumber)
23
    : new Date();
24


25
  return (
26
    <DatePicker
27
      selected={date}
28
      onChange={d => props.onChange(d.toISOString())}
29
      showTimeSelect
30
      timeFormat="p"
31
      dateFormat="Pp"
32
    />
33
  );
34
}
35


36


37
export const DateTimeSwaggerPlugin = {
38
  components: {
39
    JsonSchema_string_date: JsonSchema_string_date,
40
    "JsonSchema_string_date-time": JsonSchema_string_date_time
41
  }
42
};

请求代码段

可以使用 requestSnippetsEnabled: true 选项配置 SwaggerUI 以激活请求代码段。
它不是在执行请求时生成的通用 curl，而是为您提供更精细的选项

  • bash 的 curl
  • cmd 的 curl
  • powershell 的 curl

在某些情况下，您可能希望提供自己的代码段生成器。这可以使用插件 API 完成。
请求代码段生成器由配置和一个 fn 组成，
它接收内部请求对象并将其转换为所需的代码段。

1
// Add config to Request Snippets Configuration with an unique key like "node_native"
2
const snippetConfig = {
3
  requestSnippetsEnabled: true,
4
  requestSnippets: {
5
    generators: {
6
      "node_native": {
7
        title: "NodeJs Native",
8
        syntax: "javascript"
9
      }
10
    }
11
  }
12
}
13


14
const SnippedGeneratorNodeJsPlugin = {
15
  fn: {
16
    // use `requestSnippetGenerator_` + key from config (node_native) for generator fn
17
    requestSnippetGenerator_node_native: (request) => {
18
      const url = new Url(request.get("url"))
19
      let isMultipartFormDataRequest = false
20
      const headers = request.get("headers")
21
      if(headers && headers.size) {
22
        request.get("headers").map((val, key) => {
23
          isMultipartFormDataRequest = isMultipartFormDataRequest || /^content-type$/i.test(key) && /^multipart\/form-data$/i.test(val)
24
        })
25
      }
26
      const packageStr = url.protocol === "https:" ? "https" : "http"
27
      let reqBody = request.get("body")
28
      if (request.get("body")) {
29
        if (isMultipartFormDataRequest && ["POST", "PUT", "PATCH"].includes(request.get("method"))) {
30
          return "throw new Error(\"Currently unsupported content-type: /^multipart\\/form-data$/i\");"
31
        } else {
32
          if (!Map.isMap(reqBody)) {
33
            if (typeof reqBody !== "string") {
34
              reqBody = JSON.stringify(reqBody)
35
            }
36
          } else {
37
            reqBody = getStringBodyOfMap(request)
38
          }
39
        }
40
      } else if (!request.get("body") && request.get("method") === "POST") {
41
        reqBody = ""
42
      }
43


44
      const stringBody = "`" + (reqBody || "")
45
          .replace(/\\n/g, "\n")
46
          .replace(/`/g, "\\`")
47
        + "`"
48


49
      return `const http = require("${packageStr}");
50
const options = {
51
  "method": "${request.get("method")}",
52
  "hostname": "${url.host}",
53
  "port": ${url.port || "null"},
54
  "path": "${url.pathname}"${headers && headers.size ? `,
55
  "headers": {
56
    ${request.get("headers").map((val, key) => `"${key}": "${val}"`).valueSeq().join(",\n    ")}
57
  }` : ""}
58
};
59
const req = http.request(options, function (res) {
60
  const chunks = [];
61
  res.on("data", function (chunk) {
62
    chunks.push(chunk);
63
  });
64
  res.on("end", function () {
65
    const body = Buffer.concat(chunks);
66
    console.log(body.toString());
67
  });
68
});
69
${reqBody ? `\nreq.write(${stringBody});` : ""}
70
req.end();`
71
    }
72
  }
73
}
74


75
const ui = SwaggerUIBundle({
76
  "dom_id": "#swagger-ui",
77
  deepLinking: true,
78
  presets: [
79
    SwaggerUIBundle.presets.apis,
80
    SwaggerUIStandalonePreset
81
  ],
82
  plugins: [
83
    SwaggerUIBundle.plugins.DownloadUrl,
84
    SnippedGeneratorNodeJsPlugin
85
  ],
86
  layout: "StandaloneLayout",
87
  validatorUrl: "https://validator.swagger.io/validator",
88
  url: "https://petstore.swagger.io/v2/swagger.json",
89
  ...snippetConfig,
90
})

错误处理

SwaggerUI 附带一个 safe-render 插件，用于处理错误处理，允许插入到错误处理系统中并对其进行修改。

该插件接受应通过错误边界保护的组件名称列表。

它的公共 API 如下所示

1
{
2
  fn: {
3
    componentDidCatch,
4
    withErrorBoundary: withErrorBoundary(getSystem),
5
  },
6
  components: {
7
    ErrorBoundary,
8
    Fallback,
9
  },
10
}

safe-render 插件由 base 和 standalone SwaggerUI 预设自动使用，并且应始终作为最后一个插件使用，在所有组件都已为 SwaggerUI 所知之后。该插件定义了应通过错误边界保护的默认组件列表

1
[
2
  "App",
3
  "BaseLayout",
4
  "VersionPragmaFilter",
5
  "InfoContainer",
6
  "ServersContainer",
7
  "SchemesContainer",
8
  "AuthorizeBtnContainer",
9
  "FilterContainer",
10
  "Operations",
11
  "OperationContainer",
12
  "parameters",
13
  "responses",
14
  "OperationServers",
15
  "Models",
16
  "ModelWrapper",
17
  "Topbar",
18
  "StandaloneLayout",
19
  "onlineValidatorBadge"
20
]

如下所示，可以通过使用带有配置选项的 safe-render 插件来保护其他组件。如果您是 SwaggerUI 集成商，并且维护多个带有其他自定义组件的插件，这将非常方便。

1
const swaggerUI = SwaggerUI({
2
  url: "https://petstore.swagger.io/v2/swagger.json",
3
  dom_id: '#swagger-ui',
4
  plugins: [
5
    () => ({
6
      components: {
7
        MyCustomComponent1: () => 'my custom component',
8
      },
9
    }),
10
    SwaggerUI.plugins.SafeRender({
11
      fullOverride: true, // only the component list defined here will apply (not the default list)
12
      componentList: [
13
        "MyCustomComponent1",
14
      ],
15
    }),
16
  ],
17
});
componentDidCatch

在组件抛出错误后，将调用此静态函数。
它接收两个参数

  1. error - 抛出的错误。
  2. info - 一个对象，其中包含一个 componentStack 键，该键包含 有关哪个组件抛出错误的信息。

它的签名与错误边界 componentDidCatch 生命周期方法 完全相同，只是它是一个静态函数，而不是类方法。

componentDidCatch 的默认实现使用 console.error 来显示接收到的错误

1
export const componentDidCatch = console.error;

要利用您自己的错误处理逻辑（例如，bugsnag），请创建新的 SwaggerUI 插件，该插件会覆盖 componentDidCatch

{% highlight js linenos %} const BugsnagErrorHandlerPlugin = () => { // 初始化 bugsnag

return { fn: { componentDidCatch = (error, info) => { Bugsnag.notify(error); Bugsnag.notify(info); }, }, }; }; {% endhighlight %}

withErrorBoundary

此函数是 HOC（高阶组件）。它将特定组件包装到 ErrorBoundary 组件中。可以通过插件系统覆盖它，以控制组件如何由 ErrorBoundary 组件包装。在 99.9% 的情况下，您不需要覆盖此函数，但如果需要，请先阅读此函数的源代码。

回退

当错误边界捕获到错误时，将显示该组件。可以通过插件系统覆盖它。它的默认实现很简单

1
import React from "react"
2
import PropTypes from "prop-types"
3


4
const Fallback = ({ name }) => (
5
  <div className="fallback">
6
    😱 <i>Could not render { name === "t" ? "this component" : name }, see the console.</i>
7
  </div>
8
)
9
Fallback.propTypes = {
10
  name: PropTypes.string.isRequired,
11
}
12
export default Fallback

可以随意覆盖它以匹配您的外观

1
const CustomFallbackPlugin = () => ({
2
  components: {
3
    Fallback: ({ name } ) => `This is my custom fallback. ${name} failed to render`,
4
  },
5
});
6


7
const swaggerUI = SwaggerUI({
8
  url: "https://petstore.swagger.io/v2/swagger.json",
9
  dom_id: '#swagger-ui',
10
  plugins: [
11
    CustomFallbackPlugin,
12
  ]
13
});
ErrorBoundary

这是一个实现 React 错误边界的组件。它在底层使用了 componentDidCatch 和 Fallback。在 99.9% 的情况下，您无需覆盖此组件，但如果您确实需要这样做，请先阅读此组件的源代码。

行为变更

在 SwaggerUI 的早期版本（v4.3.0 之前）中，几乎所有组件都受到了保护，当抛出错误时，会显示 Fallback 组件。SwaggerUI v4.3.0 改变了这一点。现在只有由 safe-render 插件定义的组件才会受到保护并显示回退。如果 SwaggerUI React 组件树中的某个小组件渲染失败并抛出错误。该错误会冒泡到最近的错误边界，而该错误边界会显示 Fallback 组件并调用 componentDidCatch。

Swagger 开源
Swagger
专业工具
资源