深入了解Swagger訪問地址

Swagger是一種流行的API文檔化工具，可以通過生成API文檔和使用該文檔交互的方式簡化API測試和開發。在Swagger中，訪問地址是指API描述文件。本文將從幾個方面深入探討Swagger訪問地址的作用、用法以及相關的示例代碼。

一、創建Swagger訪問地址

我們可以在使用Swagger之前創建Swagger訪問地址。Swagger訪問地址是使用Swagger UI來訪問API文檔的URL。在許多情況下，這個URL直接由API的發布者提供。

使用下面的代碼，定義一個基本信息對象和一個路徑對象，並將它們合併成OpenAPI規範對象。這將是一個基本的示例，用於描述API的Swagger訪問地址。

const OpenApi = {
    "openapi": "3.0.0",
    "info": {
        "title": "API",
        "version": "1.0.0"
    },
    "paths": {
        "/api/users": {
            "get": {
                "summary": "Get a list of users",
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    }
};

在Swagger UI中這個URL的顯示將如下所示，我們可以非常容易地了解到API的信息:

二、獲取Swagger訪問地址

創建好Swagger訪問地址後，我們需要獲取Swagger訪問地址。這可以通過將Swagger UI包含在應用程序中實現。

使用下面的代碼，打開Swagger UI，將Swagger訪問地址傳遞給它，並將UI顯示在頁面中：

//引用SwaggerUI的JavaScript文件


//獲取DOM元素
const uiContainer = document.getElementById('swagger-ui');

//獲取Swagger訪問地址
fetch('/swagger.json')
    .then(response => response.text())
    .then(data => {
        const spec = JSON.parse(data);
        const ui = SwaggerUIBundle({
            spec: spec,
            dom_id: '#swagger-ui'
        })
        window.ui = ui
    });

這樣，我們就可以使用Swagger UI來訪問和測試API。下面是Swagger UI的一張示例截圖：

三、自定義Swagger訪問地址

在Swagger UI中，我們可以自定義Swagger訪問地址和相應的UI。這可以很大程度上提高API文檔的可讀性。

使用下面的代碼，我們可以通過設置調節Swagger UI中的訪問地址的路由，自定義Swagger訪問地址:

// 引用SwaggerUI的JavaScript文件


//獲取DOM元素
const uiContainer = document.getElementById('swagger-ui');

//引用Swagger的JavaScript文件
const swaggerJsonUrl = '/swagger.json';
//添加UI配置對象以自定義UI
const uiConfigObject = { url: swaggerJsonUrl, docExpansion: 'list', tagsSorter: 'alpha' };
//設置SwaggerUI的路由
const customRoutes = {
    validate: false,
    urls: [
        { url: "/api/docs", name: "API Doc" },
        { url: "/api/redoc", name: "API Redoc" },
        { url: "/api/custom-swagger", name: "Custom Swagger UI" }
    ]
};

通過設置一個自定義路由，我們可以輕鬆訪問到自定義的Swagger UI。下面是一個示例截圖：

四、使用Swagger Editor編輯Swagger訪問地址

Swagger Editor是一個在線編輯器，可以幫助我們更輕鬆地創建Swagger訪問地址。在Swagger Editor中，我們可以將許多定義組合在一起，並在Swagger UI中使用這個規範。Swagger Editor還帶有實時呈現和文檔化工具。

使用下面的代碼，我們可以在Swagger Editor中編輯Swagger訪問地址：

//引用Swagger Editor的網頁地址
const swaggerEditorPath = 'https://editor.swagger.io/?url=';
// 獲取Swagger訪問地址
const swaggerJsonUrl = '/swagger.json';
const encodedJsonUrl = encodeURIComponent(swaggerJsonUrl);
const swaggerEditorUrl = `${swaggerEditorPath}${swaggerJsonUrl}`;

//使用窗口打開編輯器
const editorWindow = window.open(swaggerEditorUrl, "Swagger Editor");
editorWindow.focus();

這樣，我們就可以打開Swagger Editor，開始創建和編輯Swagger訪問地址。下面是Swagger Editor的一張示例截圖：

五、通過Swagger安全控件保護Swagger訪問地址

訪問Swagger訪問地址通常需要授權。通過Swagger安全控件，我們可以在Swagger中完成身份驗證和授權操作，從而保證訪問安全性。

下面是保護Swagger訪問地址的示例代碼：

//引入Swagger中的設置
const security = [
  {
    ApiKeyAuth: []
  }
];
//API授權
SwaggerUIBundle({
  spec: spec,
  dom_id: '#swagger-ui',
  deepLinking: true,
  displayOperationId: false,
  defaultModelsExpandDepth: -1,
  presets: [
    SwaggerUIBundle.presets.apis,
    SwaggerUIStandalonePreset
  ],
  plugins: [
    SwaggerUIBundle.plugins.DownloadUrl,
    SwaggerUIBundle.plugins.SwaggerJsUrl,
    SwaggerUIBundle.plugins.ConfigsPlugin
  ],
  layout: 'BaseLayout',
  configsPlugin: {
    authActions: {
      ApiKeyAuth: {
        logout: (auth) => { console.log('Logout', auth) },
        onLoggedIn: (auth) => { console.log('Logged In', auth) }
      }
    },
    security,
    codeGeneratorOptions: {
      includeSchemes: true,
      includeProducesConsumes: true,
      includeProducesAndResponseTypes: true
    },
    useResCallback: true,
    opsStateResponses: true
  }
})

上述代碼可以保證我們在訪問Swagger訪問地址時能夠進行安全控制操作。下面是一個例子截圖：

六、總結

Swagger是一個流行的API文檔化工具，可以通過生成API文檔和使用該文檔交互的方式簡化API測試和開發。Swagger訪問地址是指API描述文件。本文從創建Swagger訪問地址、獲取Swagger訪問地址、自定義Swagger訪問地址、使用Swagger Editor編輯Swagger訪問地址以及通過Swagger安全控件保護Swagger訪問地址等多個方面闡述了Swagger訪問地址的作用、用法以及相關示例代碼。讓我們深入了解Swagger訪問地址以提高我們對Swagger的使用效率。