Swagger介绍
在线接口文档的生成工具，且支持用户在线接口测试，优点：
- 号称时最流行的 API 框架
- 接口文档在线生成，避免同步的麻烦
- 可以支持在线对接口执行测试
SpringBoot中集成Swagger
Swagger的原生UI展示的内容主观上没有那么清楚和漂亮，对此有两款对应的Swagger UI的出现，分别为SwaggerBootstrapUI和 knife4j
SwaggerBootstrapUI
- 导入swagger依赖（SwaggerBootstrapUI）
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.5.22</version>
</dependency>
java- 编写Swagger配置类 注解：springBoot的配置类注解，swagger启动注解，开启swaggerBootStrapUI Ui界面，为了方便后面参数的修改，可以在yaml中配置参数传入配置类中。 swaggerConfig.java
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class SwaggerConfig {
@Value("${swagger.enable}")
private boolean enableSwagger;
@Value("${swagger.serviceUrl}")
private String serviceUrl;
@Value("${swagger.contact}")
private String contact;
@Value("${swagger.title}")
private String title;
@Value("${swagger.version}")
private String version;
@Value("${swagger.basePackage}")
private String basePackage;
@Value("${swagger.description}")
private String description;
@Bean
public Docket createRestApi() {
//构建全局参数，有需要的在做了解，暂时只需要下面的配置
ParameterBuilder tokenpar = new ParameterBuilder();
List<Parameter> pars = new ArrayList<Parameter>();
tokenpar.name("AuthToken").description("AuthToken")
.modelRef(new ModelRef("string")).parameterType("header")
.required(false).build(); //header中的ticket参数非必填，传空也可以
pars.add(tokenpar.build()); //根据每个方法名也知道当前方法在设置什么参数
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()) //接口的信息
.enable(enableSwagger) //swagger接口网站开启配置
.select() //初始化并返回一个API选择构造器
.apis(RequestHandlerSelectors.basePackage(basePackage))//添加包路径选择条件
.paths(PathSelectors.any()) // 可选择具体路径的筛选（如："/user/"）
.build()
.globalOperationParameters(pars); //全局参数的配置
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title(title) //UI标题
.description(description) //详细描述
.termsOfServiceUrl(serviceUrl) //服务器启动路径
.contact(contact) // 作者
.version(version) //版本
.build();
}
}
java界面如图
knife4j
- 导入依赖
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<!--在引用时请在maven中央仓库搜索最新版本号-->
<version>2.0.4</version>
</dependency>
java配置和SwaggerBootstrapUI一样，配置类的注解将@EnableSwaggerBootstrapUI改为@EnableKnife4j。
常用注解
最后附上swagger2常用注解
@Api()用于类；表示标识这个类是swagger的资源
@ApiOperation()用于方法；表示一个http请求的操作
@ApiParam()用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）
@ApiModel()用于类表示对类进行说明，用于参数用实体类接收
@ApiModelProperty()用于方法，字段表示对model属性的说明或者数据操作更改
@ApiIgnore()用于类，方法，方法参数表示这个方法或者类被忽略
@ApiImplicitParam() 用于方法表示单独的请求参数
@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam 示例：
代码语言：javascript复制@Api(value="用户controller",tags={"用户操作接口"})
@RestController
public class UserController {
@ApiOperation(value="获取用户信息",tags={"获取用户信息copy"},notes="注意问题点")
@GetMapping("/getUserInfo")
public User getUserInfo(@ApiParam(name="id",value="用户id",required=true) Long id,@ApiParam(name="username",value="用户名") String username) {
// userService可忽略，是业务逻辑
User user = userService.getUserInfo();
return user;
}
}
java实体类：
代码语言：javascript复制@Data
@ApiModel(value = "微信实体类")
public class WxAuth {
@ApiModelProperty(value = "用户SessionId",required = true)
private String sessionId;
@ApiModelProperty(value = "昵称",required = true)
private String nickname;
@ApiModelProperty(value = "头像",required = true)
private String photo;
}
java界面展示：
