README

Swagger UI 是 Swagger 项目的一部分。Swagger 项目允许您生成、可视化和使用您自己的 RESTful 服务。无需代理或第三方服务。自己做。

Swagger UI 是一组无依赖的 HTML、JavaScript 和 CSS 资产，它可以从 Swagger 兼容的 API 动态生成精美的文档和沙盒。由于 Swagger UI 无依赖项，您可以在任何服务器环境中托管它，或者在您的本地计算机上托管它。

什么是 Swagger？

Swagger™ 的目标是定义一个标准、语言无关的接口，用于 REST APIs，允许人类和计算机在无需访问源代码、文档或通过网络流量检查的情况下发现和理解服务的功能。通过 Swagger 正确定义后，消费者可以以最少的实现逻辑理解并交互远程服务。类似于接口对底层编程所做的那样，Swagger 去除了调用服务时的猜测。

有关 Swagger 项目（包括对其他语言和更多内容的支持）的更多信息，请参阅 Swagger-Spec。

兼容性

自 2010 年初创建以来，Swagger 规范已经过 4 次修订。swagger-ui 与 Swagger 规范的兼容性如下

如何使用它

下载

您可以直接使用 swagger-ui 代码！无需构建或重新编译--只需克隆此存储库并使用 dist 文件夹中的预构建文件。如果您喜欢当前的 swagger-ui，请在此处停止。

浏览器支持

Swagger UI 在所有长期更新的桌面浏览器（Chrome、Safari、Firefox）中工作。Internet Explorer 支持版本为 8（IE8）及以上。

构建

您可以在自己的计算机上重新构建 swagger-ui 来调整它，或者只是为了说您已经这样做。要这样做，请按照以下步骤操作

1. npm install
2. gulp
3. 您应该在 dist 文件夹下看到发行版。在浏览器中打开 ./dist/index.html 以启动 Swagger UI。

开发

使用 gulp watch 创建新的构建并监视文件更改。

使用 Docker 构建

使用Docker容器构建swagger-ui

docker build -t swagger-ui-builder .
docker run -p 127.0.0.1:8080:8080 swagger-ui-builder

这将启动Swagger UI，并在http://localhost:8080上运行。

使用

打开Swagger UI后，它将加载Swagger Petstore服务并显示其API。您可以输入自己的服务器URL并点击“探索”来查看API。

自定义

您可以选择为您的组织自定义Swagger UI。以下是其各个目录的概述

• dist: 包含可以部署到服务器或从本地机器加载的发行版。
• dist/lang: Swagger本地化
• lib: 包含swagger-ui所依赖的javascript依赖项。
• node_modules: 包含swagger-ui开发所使用的node模块。
• src
• src/main/templates: 用于渲染swagger-ui的handlebars模板。
• src/main/html: HTML文件，一些图像和CSS。
• src/main/javascript: 主代码

SwaggerUi

要使用swagger-ui，您应该查看swagger-ui HTML页面的源代码并进行自定义。这基本上需要您实例化一个SwaggerUi对象，并在其上调用load()，如下所示

var swaggerUi = new SwaggerUi({
  url:"http://petstore.swagger.io/v2/swagger.json",
  dom_id:"swagger-ui-container"
});

swaggerUi.load();

参数

• 其他所有参数的详细说明见下文

HTTP方法和API调用

swagger-ui支持调用所有HTTP方法API，包括GET、PUT、POST、DELETE、PATCH、OPTIONS。这些在swagger-js项目中处理，请参阅那里了解它们的用法细节。

头部参数

通过swagger-js的可插拔机制支持头部参数。您可以在index.html中查看如何动态设置头部参数的示例。

// add a new SwaggerClient.ApiKeyAuthorization when the api-key changes in the ui.
$('#input_apiKey').change(function() {
  var key = $('#input_apiKey')[0].value;
  if(key && key.trim() != "") {
    swaggerUi.api.clientAuthorizations.add("key", new SwaggerClient.ApiKeyAuthorization("api_key", key, "header"));
  }
})

这将在每个调用服务器时添加带有值key的头部api_key。您可以用query替换以将值作为查询参数发送。

自定义头部参数 - （用于基本认证等）

如果您有一些需要在每个请求中发送的头部参数，请按以下方式使用头部：

swaggerUi.api.clientAuthorizations.add("key", new SwaggerClient.ApiKeyAuthorization("Authorization", "XXXX", "header"));

注意！您可以在单个请求中传递多个头部参数，只需为它们使用唯一的名称即可（在上面的示例中使用了key）。

本地化和翻译

本地化文件位于lang目录。请注意，默认情况下SwaggerUI不包括语言文件和翻译器。您需要手动添加它们。

要启用翻译，您应该在Swagger的index.html（或您使用的其他入口点）中追加以下两行：

<script src='lang/translator.js' type='text/javascript'></script>
<script src='lang/en.js' type='text/javascript'></script>

第一行脚本是一个翻译器，第二行是您的语言词汇。

如果您想添加对新语言的支持，只需创建lang/your_lang.js并像现有文件一样填写它。

要添加新的词汇以进行翻译，您需要做两件事：

1. 将词汇添加到语言文件中。新行示例：“new sentence":"new sentence的翻译"。
2. 在源HTML中用属性data-sw-translate标记此词汇。更改后的源示例

<anyHtmlTag data-sw-translate>new sentence</anyHtmlTag>
or <anyHtmlTag data-sw-translate value='new sentence'/>

.

目前只有内联HTML、title属性和value属性将被翻译。

CORS支持

或者：如何处理“无法从服务器读取。它可能没有适当的access-control-origin设置。”的问题。

CORS是一种防止网站对你的个人数据进行恶意操作的技巧。大多数浏览器和JavaScript工具包不仅支持CORS，还强制执行它，这对支持Swagger的API服务器有影响。

您可以在这里了解CORS： http://www.w3.org/TR/cors。

在两种情况下，不需要对CORS进行任何操作

1. swagger-ui与应用程序本身托管在同一个服务器上（相同的宿主 和 端口）。
2. 应用程序位于一个代理后面，该代理启用了所需的CORS头。这可能在您的组织内部已经得到解决。

否则，需要启用CORS支持

1. 您的Swagger文档。对于Swagger 2.0，是swagger.json以及任何外部$ref引用的文档，对于旧版本是资源列表和API声明文件。
2. 为了使“立即尝试”按钮工作，API端点也需要启用CORS。

测试CORS支持

您可以使用三种技术之一来验证CORS支持

• 使用curl您的API并检查头信息。例如

$ curl -I "http://petstore.swagger.io/v2/swagger.json"
HTTP/1.1 200 OK
Date: Sat, 31 Jan 2015 23:05:44 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, DELETE, PUT, PATCH, OPTIONS
Access-Control-Allow-Headers: Content-Type, api_key, Authorization
Content-Type: application/json
Content-Length: 0

这告诉我们petstore资源列表支持OPTIONS，以及以下头信息：Content-Type，api_key，Authorization。

• 从您的文件系统尝试swagger-ui并查看调试控制台。如果CORS未启用，您将看到类似以下内容

XMLHttpRequest cannot load http://sad.server.com/v2/api-docs. No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'null' is therefore not allowed access.

Swagger-UI无法轻松显示此错误状态。

• 使用http://www.test-cors.org网站。请注意，即使没有Access-Control-Allow-Headers，该网站也会显示成功的结果，这对于Swagger-UI正常工作仍然是必需的。

启用CORS

启用CORS的方法取决于您用于托管应用程序的服务器和/或框架。http://enable-cors.org提供了在常见Web服务器中启用CORS的信息。

其他服务器/框架可能提供如何在其特定用例中启用它的信息。

CORS和头参数

Swagger允许您轻松地将头信息作为参数发送到请求中。这些头的名称必须在您的CORS配置中得到支持。从我们上面的例子中

Access-Control-Allow-Headers: Content-Type, api_key, Authorization

只有这些名称的头信息才能被Swagger-UI发送。

如何改进

创建swagger-api/swagger-ui的自己的分支

要分享您的更改，请提交一个pull请求。

变更日志

请参阅发布以获取变更日志。

许可协议

版权所有2011-2015 SmartBear Software

根据Apache License，版本2.0（“许可证”）许可；除非遵守许可证，否则不得使用此文件。您可以在apache.org/licenses/LICENSE-2.0获取许可证的副本。

除非适用法律要求或书面同意，否则在许可证下分发的软件是根据“现状”原则分发的，不提供任何形式的明示或默示保证或条件。有关许可证的具体权限和限制，请参阅许可证。