最近我们实验室老师要我整理接口文档,我是用javadoc自动生成的(说前端人看不懂),没办法,只能换了~
本篇主要介绍 Swagger,一款围绕OpeanAPI规范构建的开源工具,便于构建和使用REST API
下面就介绍一下在Java中,SpringBoot集成Swagger的一些使用与介绍
前言 Swagger 是什么?其是一款围绕OpeanAPI规范构建的开源工具,便于构建和使用REST API,主要Swagger工具有:
- Swagger编辑器 - 基于浏览器的编辑器,可在其中编写OpenAPI的规范
- Swagger UI - 让编写的OpenAPI规范以交互式API文档呈现
- Swagger Codegen - 让编写的OpenAPI规范生成服务器静态文件(stubs)和客户端库
如果在SpringBoot集成Swaager的时候,其实它就是一个库,用于编写API文档
注解介绍Swagger中提供了很多注解,在不同的地方使用不同的注解
注解 | 对象范围 | 使用位置 | 常用参数(参数很多,常用的一些参数列举出来) | 例子 |
---|---|---|---|---|
@Api | 标注类是一个Swagger资源 | 类上 | String value() default “”; // 文档关于该资源描述 String[] tags() default “”; // 文档关于该资源描述 String produces() default “”; // produces (例如 “application/json, application/xml”)String consumes() default “”;// consumes (例如 “application/json, application/xml”)String protocols() default “”;// schemes (例如 http, https, ws, wss) Authorization[] authorizations() default @Authorization(value = “”); // security boolean hidden() default false; // 该资源在文档中是否被隐藏 | @Api( tags = “用户管理”, produces = “application/json”, consumes = “application/json”, protocols = “http” ) |
@ApiOperation | 描述一个API | 方法/类上 | String value(); // *** 作的描述 String notes() default “”; // *** 作的一些note | @ApiOperation( value = “获取swagger用户”, notes = “哈哈哈哈” ) |
@ApiParam | API参数描述 | 方法/参数/Filed上 仅能在 JAX-RS 1.x/2.x上使用 | 与@ApiImplicitParam 雷同 | 与@ApiImplicitParam 雷同 |
@ApiImplicitParam | API单个参数描述 | 方法上 | String name() default “”; // 参数key String value() default “”; // 参数描述 String defaultValue() default “”; // 默认值 boolean required() default false; // 是否需要必传 boolean allowMultiple() default false; // 是否允许多值 Class> dataTypeClass() default Void.class; // 数据类型 String example() default “”; // 举例 | @ApiImplicitParam( name = “id”, value = “编号”, defaultValue = “1”, required = true, allowMultiple = false, example = “1”, dataTypeClass = String.class) |
@ApiImplicitParams | 多个@ApiImplicitParam组成 | 方法上 | ApiImplicitParam[] value(); // 多个 @ApiImplicitParam组成 | ApiImplicitParams( value = { @ApiImplicitParam( name = “id”, value = “编号”, defaultValue = “1”, required = true), @ApiImplicitParam( name = “name”, value = “名称”, defaultValue = “xxx”, required = true) } ) |
@ApiModel | 对象标注为Swagger对象 | 类上 | String value() default “”; // 名称 String description() default “”; // 描述 | @ApiModel( value = “返回数据对象”, description = “返回数据”) |
@ApiModelProperty | 对象属性 | 方法/参数上 | String value() default “”;// 描述 String name() default “”; // 返回参数名称(默认是标注的参数名称) boolean required() default false; // 是否需要必传 String dataType() default “”; // 参数类型 | @ApiModelProperty( value = “返回信息” ) |
@ApiResponse | 返回Response,一般定义一些错误的状态码与描述信息 | 方法/类上 | int code(); // 状态码 String message(); // 描述 Class> response() default Void.class; // 返回数据 | @ApiResponse( code = 200, message = “获取成功” ) |
@ApiResponses | 多个@ApiResponse组成 | 方法/类上 | ApiResponse[] value(); // 多个 @ApiResponse | @ApiResponses( value = { @ApiResponse( code = 200, message = “获取成功” ), @ApiResponse( code = 200, message = “获取成功” ) } ) |
主要介绍 Swagger 与 SpringBoot项目集成
1、导包使用即先导包
<properties>
<swagger.version>2.9.2swagger.version>
properties>
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger2artifactId>
<version>${swagger.version}version>
dependency>
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger-uiartifactId>
<version>${swagger.version}version>
dependency>
2、配置
编写Swagger配置类 SwaggerConfig
@EnableSwagger2
@Configuration
public class SwaggerConfig {
// 核心 createRestApi
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com"))//扫描com 路径下的api文档
.paths(PathSelectors.any()) //路径判断
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger Study")//标题
.description("开发规范详文档细地址")//描述
.version("1.1.1")//版本号
.build();
}
}
3、使用
举例对上述各个注解进行使用介绍
1)@ApiModel 与 @ApiModelProperty 的使用,主要用于 实体类上,标注对象与对象参数的信息
@ApiModel(value = "返回数据对象", description = "返回数据")
@Data
public class Response<T> {
@ApiModelProperty(value = "状态码")
private Integer code;
@ApiModelProperty(value = "返回信息")
private String msg;
@ApiModelProperty(value = "返回数据")
private T data;
}
@Data
public class User {
@ApiModelProperty(value = "用户的姓名,比如'李四'")
private String name;
@ApiModelProperty(value = "id", required = true)
private String id;
@ApiModelProperty(value = "用户的年龄,比如:20")
private Integer age;
}
2)@Api 、 @ApiImplicitParams 、 @ApiOperation 、@ApiResponse 的使用,主要用于Controller 类上
@RestController
@Api(tags = "用户管理", produces = "application/json", consumes = "application/json", protocols = "http")
@RequestMapping("/api/v1")
public class SwaggerController {
// 接口参数具体描述
@ApiImplicitParams(value = {
@ApiImplicitParam(name = "id", value = "编号", defaultValue = "1", required = true, allowMultiple = true),
})
// 返回状态码与描述
@ApiResponses(value = {
@ApiResponse(code = 200, message = "获取成功咯~"),
@ApiResponse(code = 500, message = "服务器错误咯~")}
)
// 接口 *** 作
@ApiOperation("获取swagger用户")
@GetMapping("/swagger/user2")
public Response<User> getUser2(String id) {
User user = new User();
user.setAge(1);
user.setId("1");
user.setName("haha");
Response<User> userResponse = new Response<>();
userResponse.setCode(200);
userResponse.setData(user);
userResponse.setMsg(" *** 作成功");
return userResponse;
}
}
启动成功后,接口文档地址如下:
http://localhost:8081/swagger-ui.html
以上的相应信息展示图如下:
欢迎分享,转载请注明来源:内存溢出
评论列表(0条)