spring mvc和swagger整合
pom.xml 导入jar
| jar包 | 所属 | 备注 |
|---|---|---|
| spring-core | spring | spring核心包 |
| spring-expression | spring | spEl表达式 |
| spring-beans | spring | spring bean |
| spring-context | spring | spring上下文 |
| spring-context-support | spring | email/scheduler/freemarker支持 |
| spring-orm | spring | orm支持 |
| spring-jdbc | spring | jdbc支持 |
| spring-web | spring | springmvc支持 一般用到监听器加载applicationconfig.xml |
| spring-webmvc | spring | spring mvc |
| spring-data-jpa | spring | ORM框架，依赖于hibernate支持 |
| io.swagger.swagger-core | swagger | swagger核心包 |
| com.fasterxml.classmate | swagger | swagger依赖包 |
| com.google.guava.guava | swagger | swagger依赖包,google公司开发jar包 |
| io.springfox.springfox-swagger2 | swagger | swagger依赖包 |
| io.springfox.springfox-swagger-ui | swagger | swagger ui包 |
| com.github.caspar-chen.swagger-ui-layer | swagger | swagger-ui-layer 是替换swagger ui一个包，另外一种展现形式，但是这个包对应服务端响应状态码，不是200的话，无法显示json串，解决办法：下载源码，修改源码打包，然后放到maven的私服中，在下载到本地 |
配置spring-mvc.xml文件
<mvc:resources mapping="docs.html" location="classpath:/META-INF/resources/"/>
<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/>
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>
<mvc:default-servlet-handler/>
docs.html: 是映射swagger-ui-layer文件jar里面的/META-INF/resources/这个目录下docs.html
swagger-ui.html：是映射swagger-ui文件jar里面的/META-INF/resources/这个目录下docs.html
/webjars/**：映射到swagger-ui文件里面这个/META-INF/resources/webjars/目录下
注意点：这里用到spring mvc默认的servlet,这个是专门来处理静态资源的，在spring-mvc配置文件里面增加
mvc:default-servlet-handler，或者在web.xml文件里面配置也行，配置如下：
default
*.jpg
新建SwaggerConfig配置java类文件
public class SwaggerConfig {
public Docket customDocket() throws IOException, UNAuthorizedCallerException {
//这里判断是线上还是线下，这里我用的是枚举，需要自己写两个值 ONLINE(0),OFFLINE(1)，增加 valueOf方法
if(SwaggerEnvEnum.valueOf(edufeSetting.getEnableSwagger()) == SwaggerEnvEnum.ONLINE) {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfoOnline())
.select()
.paths(PathSelectors.none())
.build();
}else {
return new Docket(DocumentationType.SWAGGER_2)
.genericModelSubstitutes(DeferredResult.class)
.useDefaultResponseMessages(false)
.forCodeGeneration(false)
.pathMapping("/")
.select()
.build()
.apiInfo(apiInfo());
}
}
/**
* 开发和测试环境使用
* @return
*/
private ApiInfo apiInfo() {
Contact contact = new Contact("XX测试接口", "http://www.baidu.com/");
return new ApiInfoBuilder()
.contact(contact)
.title("XX接口")
.description("接口描述")
.version("1.0.0")
.build();
}
/**
* 预生成环境使用
* @return
*/
private ApiInfo apiInfoOnline() {
return new ApiInfoBuilder()
.title("")
.description("")
.license("")
.licenseUrl("")
.termsOfServiceUrl("")
.version("")
.contact(new Contact("","", ""))
.build();
}
}
swagger常用的注解配置
常用注解：
-
@Api()用于类； 表示标识这个类是swagger的资源
-
@ApiOperation()用于方法； 表示一个http请求的操作
-
@ApiParam()用于方法，参数，字段说明； 表示对参数的添加元数据（说明或是否必填等）
-
@ApiModel()用于类 表示对类进行说明，用于参数用实体类接收
-
@ApiModelProperty()用于方法，字段 表示对model属性的说明或者数据操作更改
-
@ApiIgnore()用于类，方法，方法参数 表示这个方法或者类被忽略
-
@ApiImplicitParam() 用于方法 表示单独的请求参数
-
@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam
-
具体使用举例说明： @Api() 用于类；表示标识这个类是swagger的资源 tags–表示说明 value–也是说明，可以使用tags替代 但是tags如果有多个值，会生成多个list
-
@ApiOperation() 用于方法；表示一个http请求的操作 value用于方法描述 notes用于提示内容 tags可以重新分组（视情况而用） @ApiParam() 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等） name–参数名 value–参数说明 required–是否必填
-
@ApiModel()用于类 ；表示对类进行说明，用于参数用实体类接收 value–表示对象名 description–描述 都可省略
@ApiModelProperty()用于方法，字段； 表示对model属性的说明或者数据操作更改 value–字段说明 name–重写属性名字 dataType–重写属性类型 required–是否必填 example–举例说明 hidden–隐藏
-
@ApiIgnore()用于类或者方法上，可以不被swagger显示在页面上 比较简单, 这里不做举例
@ApiImplicitParam() 用于方法 表示单独的请求参数 @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam name–参数ming value–参数说明 dataType–数据类型 paramType–参数类型 example–举例说明
参考博客：http://blog.csdn.net/u014231523/article/details/76522486