MiniMall：整合Swagger-UI自动生成接口文档

1. 什么是Swagger

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。解析代码里的注解生成JSON文件，通过Swagger UI生成网页版的接口文档，可以在上面做简单的接口调试 。

2. 集成Swagger-UI

2.1 引入依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
</dependency>

2.2 添加配置类

@EnableSwagger2
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)//
                .apiInfo(getApiInfo())//
                .select()//
                .apis(RequestHandlerSelectors.basePackage("com.autumn.mall.invest"))// 这里指定需要生成swagger接口的包路径
                .paths(PathSelectors.any())//
                .build();
    }

    private ApiInfo getApiInfo() {
        return new ApiInfoBuilder().title("招商微服务").version("1.0.0").build();
    }
}

2.3 添加注解

• controller类上增加@Api注解。
• 方法上

@PostMapping
@ApiOperation(value = "新增或编辑实体", httpMethod = "POST")
@ApiImplicitParam(name = "entity", value = "实体类", required = true)
public ResponseResult<String> save(@Valid @RequestBody T entity) {
    return new ResponseResult(CommonsResultCode.SUCCESS, getCrudService().save(entity));
}

这样三步就可以让Swagger帮我们生成save方法的接口文档了，启动服务，通过浏览器访问http://ip:port/swagger-ui.html就可以看到生成好的接口文档：

3. Swagger注解

常用到的注解有：

• Api
• ApiModel
• ApiModelProperty
• ApiOperation
• ApiImplicitParam

3.1 Api

Api 用在类上，通常用来说明该类的作用。可以标记一个Controller类做为swagger文档资源，使用方式：

@Api(value = "楼层管理")
public class FloorController extends AbstractSupportStateController<Floor, UsingState> implements FloorApi {}

• 常见属性

属性	说明
value	url的路径值
tags	设置该值时，value值将被覆盖
description	对api资源的描述
basePath	基础路径
hidden	配置为true时将在文档中隐藏

3.2 ApiOperation

ApiOperation 用在方法上，说明方法的作用，每一个url资源的定义，使用方式：

@PostMapping
@ApiOperation(value = "新增或编辑实体", httpMethod = "POST")
@ApiImplicitParam(name = "entity", value = "实体类", required = true)
public ResponseResult<String> save(@Valid @RequestBody T entity) {
    return new ResponseResult(CommonsResultCode.SUCCESS, getCrudService().save(entity));
}

• 常见属性

属性	说明
value	方法作用的描述
httpMethod	请求方法
description	对api资源的描述
hidden	配置为true时将在文档中隐藏
response	返回的对象

3.3 ApiImplicitParam

ApiImplicitParam 用在方法上，对方法的参数进行描述。若方法有多个入参，则可以使用@ApiImplicitParams注解。

• 常见属性

属性	说明
name	参数名
value	参数名称
dataType	参数类型
required	是否必要
defaultValue	默认值

3.4 ApiModel

该注解用于描述一个model的信息，使用方式：

@Data
@Entity
@Table(name = "invest_store")
@ApiModel(description = "项目")
public class Store implements IsEntity {

    @Id
    @ApiModelProperty(value = "唯一标识", dataType = "String")
    private String uuid;

    @NotBlank
    @Length(max = 32, message = "代码最大长度不超过32")
    @ApiModelProperty(value = "代码", dataType = "String")
    private String code;

    @NotBlank
    @Length(max = 64, message = "名称最大长度不超过64")
    @ApiModelProperty(value = "名称", dataType = "String")
    private String name;

    @Enumerated(value = EnumType.STRING)
    @ApiModelProperty(value = "状态", dataType = "UsingState")
    private UsingState state;

    @Length(max = 1024, message = "说明最大长度不超过64")
    @ApiModelProperty(value = "说明", dataType = "String")
    private String remark;
}

• 常见属性

属性	说明
value	model名称
description	描述信息
parent	父类

3.5 ApiModelProperty

描述model中的属性，常见属性：

属性	说明
value	字段描述
dataType	字段类型
required	是否必要

——End—— 更多精彩分享，可扫码关注微信公众号哦。