swagger-ui README

The project's README from github.com/swagger-api/swagger-ui. As one markdown file: README.md.

NPM version Build Status security scan total GitHub contributors

monthly npm installs docker registry monthly packagist installs gzip size

Introduction

Swagger UI allows anyone — be it your development team or your end consumers — to visualize and interact with the API’s resources without having any of the implementation logic in place. It’s automatically generated from your OpenAPI (formerly known as Swagger) Specification, with the visual documentation making it easy for back end implementation and client side consumption.

General

👉🏼 Want to score an easy open-source contribution? Check out our Good first issue label.

🕰️ Looking for the older version of Swagger UI? Refer to the 2.x branch.

This repository publishes three different NPM modules:

We strongly suggest that you use swagger-ui instead of swagger-ui-dist if you're building a single-page application, since swagger-ui-dist is significantly larger.

If you are looking for plain ol' HTML/JS/CSS, download the latest release and copy the contents of the /dist folder to your server.

Compatibility

The OpenAPI Specification has undergone 5 revisions since initial creation in 2010. Compatibility between Swagger UI and the OpenAPI Specification is as follows:

Swagger UI Version Release Date OpenAPI Spec compatibility Notes
5.32.0 2026-02-27 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.0.4, 3.1.0, 3.1.1, 3.1.2, 3.2.0 tag v5.32.0
5.19.0 2025-02-17 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.0.4, 3.1.0, 3.1.1, 3.1.2 tag v5.19.0
5.0.0 2023-06-12 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.1.0 tag v5.0.0
4.0.0 2021-11-03 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3 tag v4.0.0
3.18.3 2018-08-03 2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3 tag v3.18.3
3.0.21 2017-07-26 2.0 tag v3.0.21
2.2.10 2017-01-04 1.1, 1.2, 2.0 tag v2.2.10
2.1.5 2016-07-20 1.1, 1.2, 2.0 tag v2.1.5
2.0.24 2014-09-12 1.1, 1.2 tag v2.0.24
1.0.13 2013-03-08 1.1, 1.2 tag v1.0.13
1.0.1 2011-10-11 1.0, 1.1 tag v1.0.1

Anonymized analytics

SwaggerUI uses Scarf to collect anonymized installation analytics. These analytics help support the maintainers of this library and ONLY run during installation. To opt out, you can set the scarfSettings.enabled field to false in your project's package.json:

// package.json
{
  // ...
  "scarfSettings": {
    "enabled": false
  }
  // ...
}

Alternatively, you can set the environment variable SCARF_ANALYTICS to false as part of the environment that installs your npm packages, e.g., SCARF_ANALYTICS=false npm install.

Documentation

Usage

Customization

Development

Contributing

Integration Tests

End-to-end tests use Cypress. Run the full suite locally with npm run cy:ci, which starts the required servers, runs Cypress headless, and shuts the servers down afterwards - be sure you aren't running a dev server on the same ports when testing!

To debug or run individual specs interactively, use npm run cy:dev to open the Cypress runner.

To run a single spec headless, start the servers in one terminal and run that spec in another:

npm run cy:start
# in a second terminal:
npm run cy:run -- --spec "test/e2e-cypress/e2e/features/deep-linking.cy.js"

Browser support

Swagger UI works in the latest versions of Chrome, Safari, Firefox, and Edge.

Known Issues

To help with the migration, here are the currently known issues with 3.X. This list will update regularly, and will not include features that were not implemented in previous versions.

Security contact

Please disclose any security-related issues or vulnerabilities by emailing [email protected], instead of using the public issue tracker.

License

SwaggerUI is licensed under Apache 2.0 license. SwaggerUI comes with an explicit NOTICE file containing additional legal notices and information.

swagger-ui (swagger-api/swagger-ui)

Searching Database…

29K ·GitHub
Swagger-ui
这是什么？Swagger UI 能把 OpenAPI（原名 Swagger）规范转换成可交互的可视化 API 文档：你的团队或最终使用者无需任何实现代码，就能查看并试用 API 的各个接口。
它是托管服务，还是需要我自己部署的东西？需要自己部署：它是一个前端库，以三个 npm 包的形式发布 — 面向基于打包工具的单页应用的 swagger-ui、无依赖的 swagger-ui-dist，以及作为 React 组件的 swagger-ui-react — 另外还提供纯 HTML/JS/CSS 静态资源。
怎么把它跑起来？运行 npm install swagger-ui（如果你的环境装不了 npm 依赖，就用 swagger-ui-dist），然后把它指向你的规范文件；如果用纯 HTML/JS/CSS，就下载一个 release，把 /dist 文件夹里的内容复制到你的服务器上。
看文档除了浏览器还需要什么吗？不需要 — 它是纯前端的，只是一些和你的规范文件放在一起对外提供的静态资源。最新版的 Chrome、Safari、Firefox 和 Edge 都能用。
有什么已知的不足需要注意？3.X 版本有一些官方记录的已知问题：之前支持的参数只有一部分可用，JSON Form Editor 尚未实现，collectionFormat 的支持不完整，而且缺少多语言翻译。
安装的时候会不会偷偷上报数据？只有一次：Scarf 会收集匿名统计信息，而且只在 npm 安装过程中发生。可以在 package.json 里设置 scarfSettings.enabled=false，或者设置环境变量 SCARFANALYTICS=false 来关闭。
有官方的 Docker 镜像吗？有 — 仓库里提供了 Docker 构建和推送的 CI 工作流，所以你可以把 Swagger UI 当作容器来运行，而不用自己把 dist 资源复制到服务器上。
我能自定义文档的外观吗？可以 — 除了配置项之外，文档还介绍了插件 API 和自定义布局，你可以扩展或替换默认渲染的各个部分。
它支持用 OAuth2 保护的 API 吗？支持 — OAuth2 是文档里专门讲解的用法，配置好之后就能直接在界面里试用受保护的接口。
What are similar projects?redoc, swagger-codegen, OpenAPI-Specification, fastapi, openapi-generator, apisix, scalar, swag
Which topics is it in?openapi-specification, swagger-ui, openapi3, api-documentation, swagger, rest, openapi, oauth2, css, browser, documentation, developers
Creator
swagger-api
Size
622.5 MB
Stars
29K
Updated
CommitOct 16Releasev5.33.3Oct 15
Age
15y
Commits · 90 Days