caspar-chen/swagger-ui-layer

基于swagger的漂亮的接口文档

swagger-ui-layer

---

swagger-ui-layer 是一个基于swagger的前端UI实现,是为了替换了默认的swagger-ui,让生成的文档更加友好和美观

swagger-ui-layer 要依赖swagger的注解功能，因为swagger-ui-layer 仅仅只是一个前端UI界面的实现，解析的数据来源于 /v2/api-docs

效果

• 最终生成文档的展示例子：http://suldemo.tianox.com/docs.html

• 接口文档信息界面

• 接口文档调试界面

---

如何使用

1、引入jar包

首先需要在你的 pom.xml 中引入swagger 和 swagger-ui-layer 最新版的jar包

swagger-ui-layer 最新版jar包地址：http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22com.github.caspar-chen%22%20AND%20a%3A%22swagger-ui-layer%22

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.2.2</version>
</dependency>
<dependency>
  <groupId>com.github.caspar-chen</groupId>
  <artifactId>swagger-ui-layer</artifactId>
  <version>${last-version}</version>
</dependency>

2、添加swagger功能和注解

启用swagger ,创建SwaggerConfig文件，内容如下，

需要注意的一点是 swagger api 的默认地址是/v2/api-docs 所以swagger-ui-layer也读取的是默认地址， 所以在new Docket()的时候不能指定group参数，否则 swagger api 的地址会在后面加入group的参数导致swagger-ui-layer不能正确请求到数据

@Configuration
@EnableSwagger2
public class SwaggerConfig {

	@Bean
	public Docket ProductApi() {
		return new Docket(DocumentationType.SWAGGER_2)
				.genericModelSubstitutes(DeferredResult.class)
				.useDefaultResponseMessages(false)
				.forCodeGeneration(false)
				.pathMapping("/")
				.select()
				.build()
				.apiInfo(productApiInfo());
	}

	private ApiInfo productApiInfo() {
		ApiInfo apiInfo = new ApiInfo("XXX系统数据接口文档",
				"文档描述。。。",
				"1.0.0",
				"API TERMS URL",
				"联系人邮箱",
				"license",
				"license url");
		return apiInfo;
	}
}

常用的swagger注解 Api ApiModel ApiModelProperty ApiOperation ApiParam ApiResponse ApiResponses ResponseHeader 具体的注解用法可参阅互联网

3、查看结果

swagger-ui-layer 的默认访问地址是 http://${host}:${port}/docs.html

License

Apache License 2.0

源码维护地址

• Github ： https://github.com/caspar-chen/swagger-ui-layer

swagger-ui-layer's Issues

如果是在nodejs的服务器中，应该怎样部署上去呢？

这个页面布局，正是我们项目组期望已久的！但是有个疑问，现在一般都是docker直接执行nodejs环境吧？那种情况下面，怎样来部署您的这个页面布局呢？

参数是map的时候，不能显示example信息

File 字段不能弹框选择文件

response 是多层复杂json,而且是调用第三方的，可能随时加字段，怎么解决在ui显示问题

{
"code": 0,
"data": {
"cancel_fee_detail": [],
"booking_cancel_fee_detail": [],
"drivers": [],
"bookings": [],
"polling_state": 2,
"polling_count": "1",
"next": 10
},
"message": "成功"
}

接口测试时，query string 参数会 拼接两次

form 提交请求参数时，Request URL 中会将参数拼接两次
如提交请求参数：
module=asd

则 Request URL为：
http://suldemo.tianox.com/banner?module=asd&module=asd

接口测试没有状态码

不使用注解，使用编辑json的方式可以使用这个ui吗？

$ref类型没有处理

例如，{"$ref":"#/definitions/WxJsapiSignature"}，这种类型在UI中没有处理，恳求作者能够增加。

1.1.3版本与原生swagger-ui对比后发现的一些不足

本想打算用这个ui替换原生ui结果发现跟原生ui相比虽然整体上要好看一些，但同样存在不少地方反而比不上原生ui，最终暂时放弃对原生的替换。
主要问题如下：
1、@ApiModelProperty设置example参数无效，无法提供默认查询示例
2、debug中json参数只能自行输入，而原生ui只需要点击默认示例即可
3、原生ui在每次点击对应接口后url会发生变化，而swagger-ui-layer所有接口显示的url都一样，导致刷新页面后需要重新查找之前的接口
以上问题导致再开发和测试时使用反而不如原生ui好用，建议以后改进

另外建议添加对接口排序的支持。

required必填项没有校验

作者辛苦了，required必填项没有校验

没有原生的Authorize这个鉴权的东西，能否添加呢

没有原生的Authorize这个鉴权的东西，能否添加呢

当返回值为String的时候，debug没有结果显示

如图，谷歌浏览器调试模式中 Network 可以看到请求已经发出，且返回结果正常，但页面无反应。
用的 @RestController，所以无需 @responsebody。

不支持文件上传

Swagger UI正常，但是swagger-ui-layer的html提示mapping不到

框架用的是Spring Boot 2.0
swagger-ui (2.8.0)和 swagger-ui-layer (0.0.4) 也都是用的最新版本
swagger-ui用 /swagger-ui.html可以正常访问，/v2/api-docs也可以正常返回结果

但是访问swagger-ui-layer，提示
No mapping found for HTTP request with URI [/docs.html] in DispatcherServlet with name 'dispatcherServlet'

请问应该设置哪里呢？

请问一下怎么将swagger-ui-layer打包成jar 我是下载的zip我想打包成jar

能不能把defaultValue 加进去

比如debug下需要token的支持 设置了全局的头部token后,在这个项目里无法显示。每次还要重新输入。希望您加上。这个版本超赞！！！！

不能正确解析response内非$ref的schema内容

案例：

{
  "get": {
    "summary": "第一个list功能",
    "deprecated": false,
    "produces": [
      "*/*"
    ],
    "operationId": "list3GET4997028859787988992",
    "responses": {
      "200": {
        "schema": {
          "type": "object",
          "properties": {
            "id": {
              "name": "id",
              "in": "formData",
              "description": "标识的desc",
              "required": true,
              "type": "string"
            },
            "createTime": {
              "name": "createTime",
              "in": "formData",
              "description": "时间的desc",
              "required": false,
              "type": "string"
            }
          }
        },
        "description": "返回profile列表"
      }
    },
    "description": "list的description",
    "parameters": [
      {
        "name": "id",
        "in": "formData",
        "description": "标识的desc",
        "required": true,
        "type": "string"
      },
      {
        "name": "createTime",
        "in": "formData",
        "description": "时间的desc",
        "required": false,
        "type": "string"
      }
    ],
    "tags": [
      "profile"
    ],
    "consumes": [
      "application/xml"
    ]
  }
}

在responses里面的schema不能正确的展示。 该问题在springfox-swagger-ui等其他工具上可以正确展示。如果schema内容为$ref指到definitions内的元素，展示没有问题。

怎么改成中文？？

怎么改成中文？？

能否在调试页面允许填写Header字段信息

如题。token通常在头部的Authrazation里。调试页面允许填这个就会好很多。
PS：谢谢作者的工作。的确比swagger-ui好看很多。

请问有没有swagger ui layer demo的源码？

在点击Submit按钮请求接口的时候一直报错，不知道swagger的返回体注解应该怎样使用。

Header 参数并不能被加进去

groupname的使用简单修改可以支持

//从URL获取参数
function getQueryString (name) {
return decodeURIComponent((new RegExp('[?|&]'+name+'='+'([^&;]+?)(&|#|;|$)').exec(location.href)||[, ''])[1].replace(/+/g, '%20')) || null
}

var url = "v2/api-docs";
//获取group的值
if(getQueryString("group")) {
url += "?group=" + getQueryString("group");
}

修改docs.js中的ajax地址为上面的url，不知道管理有这样尝试过没

拦截器中如何配置放行

拦截器中如何配置放行呢?

0.0.2版本升级到1.1.3之后，重新启动应用，报404

0.0.2版本升级到1.1.3之后，重新启动应用，报404，访问http://localhost:8193/docs.html报404，我的应用的端口起的就是8193

Responses不能显示code，耗时等信息

当参数类型错误，返回无数据

文件上传的问题

对于文件上传没有兼容

接口过多的话，页面加载太慢

大佬 能不能优化一下

不支持file类型的参数做上传文件操作

如何才能使用groupname？

对API进行分组。如何才能使用groupname？

zuul 整合swagger-ui-layer 有问题

而现有提供swagger-ui.html 页面正常

怎么配置debug的时候带上项目名称

比如我打开网址：http://localhost:8080/project/docs.html.
里面有个mapper是persons。
如果直接在浏览器访问http://localhost:8080/project/persons，就能够得到结果。
但是在ui里点击这个接口的debug就404，因为发出的url是http://localhost:8080/persons。怎么解决

请问一下对返回LocalDateTime的处理

返回的数据类型中有LocalDateTime类型的，对这个字段使用@jsonformat转换成字符串格式显示之后，但是在ui界面还是显示的是没有转换之前的LocalDateTime的格式

请求的对象的属性说明可以加上吗

注释没有显示，Responses 返回对象里面有包含其它对象实体，实体的注释没办法显示

例如下代码，data是一个实体类，实体的注释无法显示了

@apimodel("返回响应数据ResponseResult")
public class ResponseResult {

@ApiModelProperty("错误码,1成功 0失败")
private int code;
@ApiModelProperty("执行结果描述")
private String desc;
@ApiModelProperty("版本")
private String version;
@ApiModelProperty("数据")
private T data;

在controller参数添加@RequestBody注解之后页面上不展示具体的对象字段

如题，如果在请求参数中添加了@requestbody，在页面展示的时候没有具体的字段信息

不好调试哦还有上传的类型无法测试

不好调试哦还有上传的类型无法测试

在@ApiOperation中定义的consumes = "application/json;charset=UTF-8"在页面中没有生效

示例：
@ApiOperation(value = "测试接口", notes = "测试接口",httpMethod = "POST",consumes = "application/json;charset=UTF-8")
debug时仍旧可以选择form与json，期望ApiOperation定义consumes后仅保留json。

ajax请求contenttype 问题

如果后端是 需要设置contextType=application/json的， 现在访问出错。

中文问题协助处理

以json格式提交数据：{"a":"小小","id":"id","title":"标题"}，后台收到的值为：a=%E5%B0%8F%E5%B0%8F&id=id&title=%E6%A0%87%E9%A2%98，使用Postman正常

Spring Cloud如何整合swagger-ui-layer?

引入的spring4all的swagger-spring-boot-starter依赖

建議請求失敗時，將返回內容顯示在頁面中

建議請求失敗時，也將返回內容顯示在頁面中(Responses下方)，現在使用彈出dialog顯示不方便。

RequestMethod的类型为post以及put的restful接口其Responses为空白？

1、RequestMethod的类型为post以及put的restful接口其Responses为空白？

2、即便在接口使用@ApiResponses或者@ApiResponse，接口界面也是显示为空白，源码的BUG？

响应体里的范型无法显示

返回对象里嵌套对象不能显示完全

比如返回json对象
{"code":200,"msg":"消息","data":{"id":1,"userName":"admin"}}
显示出来的效果为

Properties	Type	Description
code	integer	描述
data	object	描述
msg	string	描述

0.0.4的webjar对json提交还是有点小问题

如题，
后端接口的body体为json格式。
前端切换为json格式后，提交时payload依然是键值对。

脚本错误

Uncaught TypeError: Cannot read property 'url' of undefined
at Function.eval [as fn] (eval at L (jsrender.min.js:3), :19:24)
at F (jsrender.min.js:3)
at Function.S [as render] (jsrender.min.js:3)
at m.fn.init.Z [as render] (jsrender.min.js:3)
at Object.success (docs.js:24)
at j (jquery.js:2)
at Object.fireWith [as resolveWith] (jquery.js:2)
at x (jquery.js:4)
at b (jquery.js:4)
at Object.send (jquery.js:4)

docs.html页面结构有问题debug不能使用

主要是少了两个dev加ayui-tab-item嵌套导致的，附上源码有点乱，给取消了，大家可以自己手动改下

接口debug中，如果返回值为空，显示的还是上一次调用接口的返回值

如题

requestbody是对象的话，dataType中显示为空

Deprecated的api没有删除线标志

springfox的swagger-ui会展示成删除线的样式。