跳至內容

外掛點

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
}

標誌元件

使用獨立預設時，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 綱要元件

在 swagger 中，有所謂的 JSON 綱要元件。這些元件用於使用 application/x-www-form-urlencoded 或 multipart/* 媒體類型來呈現參數和請求主體元件的輸入。

在內部，swagger 使用下列對應來從 OpenAPI 規格綱要資訊中尋找 JSON 綱要元件

對於每個綱要的類型（例如 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

這需要兩個元件，以及簡單的邏輯來移除格式為 date 時的任何時間輸入

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
}

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
]

如下所示，可以使用具有組態選項的安全轉譯外掛程式來保護其他元件。如果您是 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 外掛程式定義的元件才會受到保護並顯示 fallback。如果 SwaggerUI React 元件樹中的某個小型元件無法渲染並拋出錯誤。該錯誤會向上冒泡到最接近的錯誤邊界，而該錯誤邊界會顯示 Fallback 元件並調用 componentDidCatch。

Swagger 開源
Swagger
專業工具
資源