java自定义ui_认识和使用工具之Swagger 自定义UI界面（Java）

Swagger 自定义UI界面

Swagger简单介绍

如何使用Swagger

添加自定义UI界面

使用swagger-ui-layer

Swagger简单介绍

Swagger是一个Restful风格接口的文档在线自动生成和测试的框架

官网：http://swagger.io

官方描述：The World’s Most Popular Framework for APIs.html

Swagger ui 的原生UI界面以下：前端

我的感受原生UI显示的有些不够漂亮和清晰，特别是request 的model部分

因此想从新设计一个更加友好美观的UI界面。git

最后的效果图以下：

接口文档信息界面github

接口文档调试界面web

实现原理：

由于Swagger-ui读取的数据来源于/v2/api-docs，而且返回的是json数据。

因此只要本身写一个页面去解析json数据，并展示就能够实现自定义swagger的UI界面了ajax

如何使用Swagger

一、引入jar包

首先须要在你的 pom.xml 中引入swagger的包spring

io.springfox

springfox-swagger2

2.2.2

2.启用swagger

启用swagger ,建立SwaggerConfig文件，内容以下，json

@Configuration

@EnableSwagger2

public class SwaggerConfig {api

@Bean

public Docket ProductApi() {

return new Docket(DocumentationType.SWAGGER_2)

.genericModelSubstitutes(DeferredResult.class)

.useDefaultResponseMessages(false)

.forCodeGeneration(false)

.pathMapping("/")

.select()

.build()

.apiInfo(productApiInfo());

}app

private ApiInfo productApiInfo() {

ApiInfo apiInfo = new ApiInfo("XXX系统数据接口文档",

"文档描述。。。",

"1.0.0",

"API TERMS URL",

"联系人邮箱",

"license",

"license url");

return apiInfo;

}

3.添加swagger注解

经常使用的swagger注解

Api

ApiModel

ApiModelProperty

ApiOperation

ApiParam

ApiResponse

ApiResponses

ResponseHeader

具体能够参考swagger官方注解文档：http://docs.swagger.io/swagger-core/apidocs/index.html

4.添加自定义UI界面

有两种方式

1.能够在项目的基础上新增一个servlet ,指向对应的html文件

html文件里再去解析json，并渲染UI

2.新建一个项目，用webjars将前端资源打成jar包，再供其余项目使用

项目结构如图

主要文件是docs.html，此文件做用是解析json和渲染UI

经过ajax请求v2/api-docs,再解析json。

$.ajax({

url : "v2/api-docs",

//url : "http://petstore.swagger.io/v2/swagger.json",

dataType : "json",

type : "get",

success : function(data) {

//do something

console.log(data);

}

});

这里为了页面方便渲染，还用到了jsrender模板引擎

完整 html 源码以下

https://github.com/caspar-chen/swagger-ui-layer/blob/master/swagger-ui-layer/src/main/resources/docs.html

使用swagger-ui-layer

如今已经将项目在github上开源了，取名为swagger-ui-layer。

欢迎star,fork,commit，也能够随意修改为本身喜欢的UI风格

github地址：https://github.com/caspar-chen/swagger-ui-layer

码云地址：https://www.oschina.net/p/swagger-ui-layer

要使用swagger-ui-layer很简单

只须要在pom.xml中加入引用最新版本jar包就能够了

最新版jar包地址：

http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22com.github.caspar-chen%22%20AND%20a%3A%22swagger-ui-layer%22

com.github.caspar-chen

swagger-ui-layer