30 Star 137 Fork 28

永夜 / swagger-document-ui

加入 Gitee
与超过 1200万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
克隆/下载
README.md 3.42 KB
一键复制 编辑 原始数据 按行查看 历史
永夜 提交于 2019-10-03 20:02 . update README.md

License Build Status Maven Central star

Swagger 规范接口的 UI


  • 主要体现文档的可读性功能,给接口调用者提供接口文档,省去文档编写。
  • 此项目没有类似官方的在线测试/调试功能,建议使用 Postman,Postman 默认支持 swagger 规范的接口导入,但文件夹结构不与文档一致,所以定制了 Postman 导出功能。
  • 在线样例
  • 更新日志

使用方式

springfox 框架集成

  1. 移除官方 UI 依赖
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${springfox.version}</version>
</dependency>
  1. 添加 swagger-document-ui 依赖
<dependency>
    <groupId>cn.javaer.springfox</groupId>
    <artifactId>swagger-document-ui</artifactId>
    <version>1.0.2</version>
</dependency>

Spring Boot 集成

与 Spring Boot 集成使用是最简单的方式,推荐使用 程序猿 DD/spring-boot-starter-swagger 提供的集成方式,然后你需要:

  1. 排除自带 UI 依赖
<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>${swagger-spring-boot-starter.version}</version>
    <!--排除自带 UI 依赖-->
    <exclusions>
        <exclusion>
            <artifactId>springfox-swagger-ui</artifactId>
            <groupId>io.springfox</groupId>
        </exclusion>
    </exclusions>
</dependency>
  1. 添加 swagger-document-ui 依赖
<dependency>
    <groupId>cn.javaer.springfox</groupId>
    <artifactId>swagger-document-ui</artifactId>
    <version>1.0.2</version>
</dependency>

静态资源部署

此项目最终是生成纯静态资源,只要将 dist 目录里的静态文件部署到 web 服务器下即可使用,但前提是:你的项目中使用了 swagger 规范的 API 信息接口。

  1. 其会请求 /swagger-resources (springfox 框架默认地址) 和 /swagger-resources.json (本项目新增地址) 拿到 API 信息接口地址。
  2. 请求 swagger-resources 中配置的 url(优先) 或者 location(兼容旧版不提供 url 字段) 其应当返回 swagger 规范的 API 信息即可使用。
  3. 可参考在线样例的部署方式,分支:online-demo

效果预览

右侧文档锚点导航

分组选择 API

模糊搜索

  • 支持中文,拼音,英文
  • 可搜索 API 名称,分类名称,url 路径

导出 Postman

JavaScript
1
https://gitee.com/cn-src/swagger-document-ui.git
git@gitee.com:cn-src/swagger-document-ui.git
cn-src
swagger-document-ui
swagger-document-ui
master

搜索帮助