跳到内容

插槽点

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 组件

使用 Standalone Preset 时，SwaggerUI 的 Logo 会在顶部栏中呈现。可以通过插件 API 替换 Logo 组件来更换 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
};

请求代码片段

SwaggerUI 可以通过 requestSnippetsEnabled: true 选项配置来激活请求代码片段。
而不是执行请求时生成的通用 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。

© . All rights reserved.