README

govtnz/swagger-ui

这是一个Swagger UI的分支，添加了少量修改（无变更）以辅助与Silverstripe集成。请阅读SILVERSTRIPE.md以了解详情。此README.md文件其余部分未变更。

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

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

什么是Swagger？

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

查看Swagger-Spec获取有关Swagger项目的更多信息，包括支持其他语言的额外库等。

兼容性

自2010年首次创建以来，Swagger规范已进行了4次修订。swagger-ui与Swagger规范之间的兼容性如下

如何使用它

下载

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

浏览器支持

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

构建

您可以在自己的环境中重新构建swagger-ui进行微调，或者只是想说您已经做了。为此，请按照以下步骤操作

npm install
gulp
您应该在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

要使用 SwaggerUi，你应该查看 SwaggerUi HTML 页面的源码并对其进行自定义。这基本上要求你实例化一个 SwaggerUi 对象，并如下调用它的 load() 方法

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

swaggerUi.load();

参数

所有其他参数的详细解释见下文

HTTP 方法及 API 调用

SwaggerUi 支持调用所有 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"));
  }
})

这将向每个服务器调用添加头部 api_key，值为 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 并像现有文件那样填写它。

要添加新的词汇用于翻译，你需要做两件事

将词汇添加到语言文件中。例如新行： "new sentence":"new sentence 的翻译"。
在源 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 支持采取行动

SwaggerUi 与应用程序本身托管在同一服务器上（同一主机和端口）。
应用程序位于启用所需 CORS 头部的代理后面。这可能已经在你的组织中得到解决。

否则，需要为 CORS 支持启用以下内容

你的 Swagger 文档。对于 Swagger 2.0，是 swagger.json 和任何外部 $ref 引用的文档，对于旧版本是 Resource Listing 和 API Declaration 文件。
为了使 "立即尝试" 按钮正常工作，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

这告诉我们宠物商店资源列表支持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请求。

更改日志

请查看releases以获取更改日志。

许可证

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

除非适用法律要求或书面同意，否则在许可证下分发的软件按“原样”分发，不提供任何明示或暗示的保证或条件。有关许可证中规定的权限和限制的具体语言，请参阅许可证。

govtnz / swagger-ui

维护者

详细信息