Swagger 介绍（Swagger 与 SpringBoot 集成）

Swagger 介绍（Swagger 与 SpringBoot 集成）

最近我们实验室老师要我整理接口文档，我是用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

以上的相应信息展示图如下：