Swagger UI官方版

Swagger UI简介

Swagger UI是一个API可视化和交互软件。如果需要编辑API，可以通过这个软件进行编辑。该软件可以与SwaggerHub结合使用，让企业团队快速编辑新的API，加快其他程序的开发进程。现在很多企业都会构建自己的API文件，当需要开发新项目时，可以直接导入API内容来辅助开发，从而快速构建项目。节省项目开发时间。如果需要设计新的api，可以下载这个软件进行编辑，提供标准化的API文档编辑方法，快速可视化API文档，方便用户更好地查看代码内容，更好地将代码导入到新项目中。Swagger UI允许您深入链接到规范中的标签和作品。当您在运行时为Swagger UI提供一个L片段时，它将自动展开并移动到指定的标记。

Swagger UI软件功能

Swagger UI是一个开源项目，用于可视化呈现由OpenAPI(swag)规范定义的API的文档。Swagger UI使您能够在不使用任何实现逻辑的情况下可视化API资源并与之交互，从而简化后端实现和客户端使用。

Swagger UI允许任何人，无论您是开发团队还是最终用户，在没有任何实现逻辑的情况下可视化API资源并与之交互。它是根据你的OpenAPI(以前叫swag)规范自动生成的，并且有可视化的文档，可以简化后端实现和客户端使用。

Swagger 2.0、OpenAPI 3.0规范支持

自动生成的交互式应用编程接口文档

高级编辑

带有基本样式验证的YAML编辑器

实时验证

智能自动完成

无代码模拟

风格指南执行

可重用组件

托管和

云托管

集中式定义存储

应用编程接口定义的版本控制

协作和共享

访问控制和安全共享

问题跟踪和评论

变化

第三方集成

与源代码管理同步

部署到应用编程接口

网络挂钩

Swagger UI软件特色

无依赖性

用户界面可以在任何开发环境中使用，无论是在本地还是在网络中。

教化

为了方便，允许最终开发人员轻松交互并尝试API公开的每一项工作。

易于浏览

有组织的文档可以快速找到并使用资源和端点。

所有浏览器都支持

Swagger UI可以在所有主要浏览器中使用，以适应各种可能的情况。

完全可定制

样式，并通过完整的源代码访问以所需的方式调整Swagger UI。

美洲国家组织完全支持

可视化斯瓦格2.0或OAS 3.0中定义的API

Swagger UI教程

固定

分销渠道

NPM登记处

我们向npm发布了两个模块:swag-ui和swag-ui-dist。

swaggy-ui由包含模块绑定的JavaScpt Web项目使用(如Webpack、Bwsefy和Rollup)。主文件导出Swagger UI的主函数，模块还包含一个命名空间样式表swag-ui/dist/swag-ui . CSS，这是一个例子:

相反，swag-ui-dist用于需要资产的最终项目。导入模块时，模块包含一个绝对路径辅助函数，该函数返回swag-ui-dist模块安装位置的绝对文件系统路径。

注意:我们建议您在工具允许的情况下使用swag-ui，因为这个swag-ui-dist会导致更多的代码在网络上传播。

模块的内容反映了您在Git存储库中看到的文件夹。最有用的文件是swag-ui-bundle . js，它是Swagger UI的内部版本，它包含了在一个文件中运行所需的所有代码。该文件夹还包含index.html资产，可以轻松地提供Swagger UI，如下所示:

该模块还导出了SwaggerUIBundle和SwaggerUIStandalonePreset，因此，如果您在一个无法处理传统npm模块的JavaScpt项目中，您可以执行以下操作:

您可以直接从Docker Hub中提取预构建的stagger-ui Docker图像:

Nginx将从端口80上的Swagger UI开始。

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

docker run-p 80:8080-e swag _ ON =/foo/swag . JSON-v/bar:/foo swag gerapi/swag-ui

您可以通过指定BASE_L环境变量来更改Web应用程序的基本L:

docker run-p 80:8080-e BASE _ L =/swag-e swag _ ON =/foo/swag . JSON-v/bar:/foo swag gerapi/swag-ui

这将使用Swagger UI/on/swag代替。

克-奥二氏分级量表

CORS是一项防止网站不当处理您的个人数据的技术。大多数浏览器+JavaScpt工具包不仅支持CORS，还支持CORS，这影响了支持Swagger的API。

在两种情况下，无需采取任何措施即可获得CORS的支持:

Swagger UI与应用程序本身位于同一主机和端口上。

应用程序位于启用所需CORS标头的代理后面。这可能已经包含在您的组织中。

否则，需要为以下方面启用CORS支持:

1.你的斯瓦格文件。对于斯瓦格2.0，它是一个由swagger.json/swagger.yaml和任何外部$ref编辑的文档。

2.为了让“立即尝试”按钮工作，需要在您的应用编程接口端点上启用CORS。

测试CORS支持

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

卷曲你的应用编程接口，并命名它。示例:

这告诉我们PetStore中的资源列表所支持的选项，以及下面的标题:Content-Type、api_key、Authozation。

在文件系统中尝试Swagger UI以查看调试控制台。如果未启用CORS，您将看到以下内容:

XMLHttpRequest无法加载http://sad..com/v2/api-docs。没有& # 8216；访问-控制-允许-登录& # 8217；请求的资源上存在标头。奥金& # 8216；null & # 8217因此不允许访问。

Swagger UI这个错误状态不容易显示。

使用http://www.test-cors.org网站验证CORS的支持。请记住，即使访问-控制-允许-标题不可用，它也会显示成功的结果，这对于Swagger UI正常运行仍然是必要的。

启用CORS

启用CORS的方法取决于您用来托管应用程序的和/或框架。Http://enable-cors.org提供了如何在一些通用网络中启用CORS的信息。

其他/框架可能会为您提供如何在它们的用例中具体启用它的信息。

CORS和报头参数

Swagger UI使您能够轻松地将标头作为参数发送到请求。CORS配置中也必须支持这些标头的名称。从上面的例子来看:

访问-控制-允许-标题:内容-类型，api_key，授权

Swagger UI只允许发送具有这些名称的标头。

Swagger UI局限

禁止的标题名称

由于网络浏览器的内置安全功能，某些标题名称无法由网络应用程序控制。

禁止的标题包括:

接受字符集

接受代码

访问控制请求头

访问控制请求方法

接触

内容长度

饼干

烹饪2

时期

二硝基甲苯

估计

圣体

坐立不安

起源

代理人-*

第二次*

裁判员

大调音阶的第7音

拖车

传输编码

提升

及格