README

新！

这是swagger-ui的新版本，3.x。想了解更多？查看我们的FAQ。

👉🏼 想要轻松贡献开源项目？ 查看我们的 Good first issue 标签。

作为一个全新的版本，从头开始编写，有一些已知问题和未实现的功能。查看已知问题部分以获取更多详细信息。

此存储库发布到两个不同的NPM模块

swagger-ui 是一个传统的npm模块，旨在用于能够解决依赖关系的JavaScript Web应用项目（通过Webpack、Browserify等）。
swagger-ui-dist 是一个无依赖的模块，包括在服务器端项目或无法解决npm模块依赖关系的Web项目中提供Swagger-UI所需的一切。

有关旧版swagger-ui，请参阅2.x分支。

兼容性

OpenAPI规范自2010年首次创建以来已经过5次修订。swagger-ui与OpenAPI规范之间的兼容性如下

如何运行

简单启动！Docker

您可以直接从Docker Hub拉取预构建的swagger-ui Docker镜像

docker pull swaggerapi/swagger-ui
docker run -p 80:8080 swaggerapi/swagger-ui

将在端口80上启动nginx，并运行swagger-ui。

或者您可以在您的主机上提供自己的swagger.json

docker run -p 80:8080 -e SWAGGER_JSON=/foo/swagger.json -v /bar:/foo swaggerapi/swagger-ui

先决条件

Node 6.x
NPM 3.x

如果您只想查看规范，请直接在您的文件系统中打开浏览器中的dist/index.html。

如果您想修改代码库，请使用npm run dev运行开发服务器。开发服务器将在3200上打开。

如果您想使用代码库更改重新构建/dist文件夹，请运行npm run build。

集成测试

根据此处的要求，您需要JDK版本7或更高

可以使用npm run e2e在本地运行集成测试 - 测试时请确保没有运行开发服务器！

浏览器支持

Swagger UI在最新版本的Chrome、Safari、Firefox、Edge和IE11中运行。

已知问题

为了帮助迁移，以下是3.X版本中目前已知的问题。此列表将定期更新，并且不会包括在以前版本中未实现的功能。

只有部分以前支持的参数可用。
JSON表单编辑器未实现。
对collectionFormat的支持是部分的。
l10n（翻译）未实现。
外部文件相对路径支持尚未实现。

直接使用JS和CSS资产

要将JS、CSS和图像资产直接包含到网页中，请使用swagger-ui-dist包。此包的根目录包含本仓库dist/目录的内容。作为node模块，swagger-ui-dist还导出了swagger-ui-bundle和swagger-ui-standalone-preset对象。

SwaggerUIBundle

要使用swagger-ui的包，请查看swagger-ui html页面的源代码并进行自定义。这基本上需要您像下面这样实例化一个SwaggerUi对象

  const ui = SwaggerUIBundle({
      url: "http://petstore.swagger.io/v2/swagger.json",
      dom_id: '#swagger-ui',
      presets: [
        SwaggerUIBundle.presets.apis,
        SwaggerUIStandalonePreset
      ],
      plugins: [
        SwaggerUIBundle.plugins.DownloadUrl
      ],
      layout: "StandaloneLayout"
    })

OAuth2配置

您可以通过在SwaggerUIBundle实例中调用initOAuth方法并传递配置来配置OAuth2授权，这些配置包括默认的client_id和client_secret、realm、应用程序名称appName、scopeSeparator、additionalQueryStringParams和useBasicAuthenticationWithAccessCodeGrant。

const ui = SwaggerUIBundle({...})

// Method can be called in any place after calling constructor SwaggerUIBundle
ui.initOAuth({
    clientId: "your-client-id",
    clientSecret: "your-client-secret-if-required",
    realm: "your-realms",
    appName: "your-app-name",
    scopeSeparator: " ",
    additionalQueryStringParams: {test: "hello"}
  })

如果您想通过npm使用包文件，请查看swagger-ui-dist包。

参数

参数名中带有点的参数是用于组织子参数的单个字符串，并不表示嵌套结构。

插件

顶栏插件

顶栏插件启用带有输入框的顶栏，用于输入规范路径和探索按钮或下拉菜单（如果使用urls）。默认情况下，插件是启用的，要禁用它，您需要从src/standalone/index.js中的预设中删除Topbar插件。

let preset = [
  // TopbarPlugin,
  ConfigsPlugin,
  () => {
    return {
      components: { StandaloneLayout }
    }
  }
]

配置插件

配置插件允许从外部获取配置而不是将它们传递给SwaggerUIBundle。获取到的配置支持两种格式：JSON或yaml。插件默认启用。有三种传递配置的方式

添加一个带有服务器URL的查询参数config，该服务器托管着配置。例如：http://petstore.swagger.io/?config=http://localhost:3001/config.yaml
添加一个configUrl配置，其中包含SwaggerUIBundle的URL
更改swagger-config.yaml中的默认配置注意：更改后，项目必须重新构建

这些选项可以一起使用，继承顺序如下（从最低优先级到最高）：swagger-config.yaml -> 传递给SwaggerUIBundle的配置 -> 传递给SwaggerUIBundle的从configUrl获取的配置 -> 作为查询参数传递的从URL获取的配置

CORS支持

CORS是一种防止网站对您的个人数据做出不良行为的技巧。大多数浏览器和JavaScript工具包不仅支持CORS，而且强制实施它，这对支持Swagger的API服务器有影响。

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

有三种情况不需要为CORS支持采取任何行动

swagger-ui托管在与应用程序本身相同的服务器上（相同的宿主和端口）。
应用程序位于启用所需CORS头部的代理后面。这可能在您的组织中已经涵盖。

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

您的Swagger文档。对于Swagger 2.0，它是swagger.json/swagger.yaml以及任何外部$ref文档。
为了使“立即尝试”按钮正常工作，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发送。

安全联系方式

请通过发送电子邮件至security@swagger.io披露任何与安全相关的漏洞或问题，而不是使用公共问题跟踪器。

许可协议

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

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

dreamfactory / df-swagger-ui

维护者

详情