swagger-bootstrap-ui是国人基于swagger的一个增强框架,主要做了页面上的优化。
导入相关包
swagger注解Api包(dto、vo、entity中字段注释和接口注释会用到即对于微服务api中会用到):
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
swagger-bootstrap-ui包:
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
Swagger配置类
package com.my.test.member.biz.swagger;
import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class SwaggerConfig {
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2).
apiInfo(apiInfo()).
select().
//扫描包的路径,即该包下面的类会被swagger文档识别一般就是控制器的包
apis(RequestHandlerSelectors.basePackage("com.my.test.member.biz.controller")).
paths(PathSelectors.any()).build()
;
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder().
title("测试用户服务").
termsOfServiceUrl("").
contact(new Contact("xxx","xxx","xxx")).version("1.0").build();
}
}
启动项目访问http://127.0.0.1:8080/doc.html:
注意一个点就是SwaggerConfig配置类需要被spring ioc托管,所以对于spring boot项目该类需要写在启动类所在包或其子包下面。
常用Api介绍:
@ApiModelProperty:一般用于entity、dto、vo中的字段注释-@ApiModelProperty(“姓名”)
@ApiModel:一般用于entity类的注释-@ApiModel(“测试身份证表”)
@Api:一般用于controller类的注释-@Api(value = “测试身份证表控制器”, tags = {“测试身份证表控制器”})
@ApiOperation:一般用于注释接口-@ApiOperation(value = “测试身份证表逻辑删除”, notes = “测试身份证表逻辑删除”)
接口上的入参和应答类型应当定义为具体的类否则swagger识别不了入参或者该接口返回数据的字段信息,不要定义为Object或者Map:
像这种swagger中该接口的入参就可以识别到TestIdcardQueryDTO中的字段和Page中的字段,响应参数也可以识别到TestIdcardEntity中的字段:
文档管理中全局参数设置可以为每个接口都设置共有的参数,比如在header中设置accessToken:
如果有遇到swagger文档中文乱码,包括通过swagger请求接口,输出的日志也是中文乱码,可以通过以下方式解决:
添加环境变量:MAVEN_OPTS 环境变量值:-Xms256m -Xmx512m -Dfile.encoding=UTF-8
添加完成后,重启服务,再次访问swagger。