README

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

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

什么是 Swagger？

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

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

如何使用它

下载

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

构建

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

安装 handlebars
安装 java
npm install
npm run-script build
您应该在 dist 文件夹下看到发行版。在浏览器中打开 ./dist/index.html 以启动 Swagger UI

使用

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

自定义

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

dist: 包含可以部署到服务器或从本地机器加载的发行版。
bin: 包含 swagger-ui 构建和测试使用的文件。这些文件不是发行版所必需的。
lib: 包含 swagger-ui 依赖的 JavaScript 依赖项。
node_modules: 包含 swagger-ui 开发所使用的 node 模块。
src - src/main/coffeescript: 主要的 CoffeeScript 代码 - src/main/templates: handlebars 模板，用于渲染 swagger-ui - src/main/html: html 文件，一些图像和 css - src/main/javascript: 一些由 CoffeeScript 代码引用的遗留 JavaScript

SwaggerUi

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

    window.swaggerUi = new SwaggerUi({
        url:"http://petstore.swagger.wordnik.com/api/api-docs",
        dom_id:"swagger-ui-container"
    });

    window.swaggerUi.load();

url参数应指向符合Swagger规范的资源列表URL
dom_id参数是SwaggerUi将用户界面放入其中的DOM元素的ID
booleanValues SwaggerUI将布尔数据类型渲染为下拉列表。默认情况下，它提供了"true"和"false"字符串作为可能的选项。您可以使用此参数更改下拉列表中的值，例如，通过将booleanValues设置为new Array(0, 1)来更改值为0和1
docExpansion控制API列表的显示方式。它可以设置为'none'（默认）、'list'（显示每个资源的操作）或'full'（完全展开：显示操作及其详细信息）
onComplete是一个回调函数参数，可以将它传递以在SwaggerUI成功渲染后通知
onFailure是一个回调函数参数，可以将它传递以在SwaggerUI遇到失败且无法渲染时通知
所有其他参数的详细解释见下文

HTTP方法和API调用

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

头参数

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

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

这将向每次调用服务器时添加头api_key，其值为key。您可以将query替换为发送查询参数的值。

自定义头参数 - （用于基本身份验证等）

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

window.authorizations.add("key", new ApiKeyAuthorization("Authorization", "XXXX", "header"));

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

如何改进

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

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

由于javascript文件是从coffeescript编译的，请提交更改到*.coffee文件！我们只能拒绝.js文件中的更改，因为它们将在每次构建UI时丢失。

许可证

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

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

domandtom / swagger-ui

维护者

详细信息