tmerclub-doc/基本开发文档/Swagger文档.md

Swagger文档

不管是knife4j还是swagger-bootstrap-ui，对外提供的地址依然是doc.html

本系统文档的访问路径：域名+端口+/doc.html，例如：http://localhost:8000/doc.html

​ 注：8000为本系统网关的端口

Knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui。

swagger官网

knife4j官方文档

添加依赖

<knife4j.version>3.0.2</knife4j.version>

<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>knife4j-micro-spring-boot-starter</artifactId>
	<version>${knife4j.version}</version>
</dependency>
<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>knife4j-spring-boot-starter</artifactId>
	<version>${knife4j.version}</version>
</dependency>

添加配置类并开启

在本系统的每个微服务模块的config文件夹中，有swagger相应的配置类，以rbac模块为例，配置如下：

@Configuration
@EnableSwagger2
@EnableKnife4j
public class SwaggerConfiguration {

	@Bean
	public Docket baseRestApi() {
		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
				.apis(RequestHandlerSelectors.basePackage("com.mall4j.cloud.rbac.controller")).paths(PathSelectors.any())
				.build();
	}

	@Bean
	public ApiInfo apiInfo() {
		return new ApiInfoBuilder().title("tmerclub商城接口文档").description("tmerclub商城接口文档Swagger版").termsOfServiceUrl("")
				.contact(new Contact("广州市蓝海创新科技有限公司", "", "")).version("1.0").build();
	}
}

特别要注意的是，类中配置了api文件也就是controller包的路径，否则生成的文档无法成功扫描接口。

.apis(RequestHandlerSelectors.basePackage("com.mall4j.cloud.rbac.controller"))

用@Configuration注解该类，让spring管理这个类

用@Bean标注方法等价于XML中配置bean

用@EnableSwagger2标识要开启Swagger2

用@EnableKnife4j标识要开启Knife4j

接口使用

在配置好之后，我们就可以对swagger进行使用,比如在SpuTagController类中

@RestController("appSpuTagController")
@RequestMapping("/ua/spu_tag")
@Api(tags = "商品分组表")
public class SpuTagController {

    @Autowired
    private SpuTagService spuTagService;

    @GetMapping("/list")
    @ApiOperation(value = "获取商品分组列表", notes = "获取商品分组列表")
    @ApiImplicitParam(name = "shopId", value = "店铺id", dataType = "Long")
    public ServerResponseEntity<List<SpuTagVO>> list(@RequestParam(value = "shopId", defaultValue = "0") Long shopId) {
        List<SpuTagVO> categories = spuTagService.listByShopId(shopId);
        return ServerResponseEntity.success(categories);
    }
}

@Api(tags="商品分组表")定义标签分组接口，在这个类下定义的所有接口将位于这个标签之下

@ApiOperation(value = "获取商品分组列表", notes = "获取商品分组列表")定义具体的接口标题信息，notes可以为这个标签添加注释

@ApiImplicitParam(name = "shopId", value = "店铺id", dataType = "Long")对应的参数列表信息，后端返回给前端开发人员，这个接口需要传递什么参数及参数的说明

如有多个参数需要说明，可使用@ApiImplicitParams()下面可包含多个@ApiImplicitParam()

例如：

@ApiImplicitParams({
            @ApiImplicitParam(name = "parentId", value = "分类ID", dataType = "Long"),
            @ApiImplicitParam(name = "shopId", value = "店铺id", dataType = "Long")
    })

实体类

public class ChangeShopCartItemDTO {

    @ApiModelProperty(value = "购物车ID", required = true)
    private Long shopCartItemId;

    @NotNull(message = "商品ID不能为空")
    @ApiModelProperty(value = "商品ID", required = true)
    private Long spuId;

    @ApiModelProperty(value = "旧的skuId 如果传过来说明在变更sku", required = true)
    private Long oldSkuId;

    @NotNull(message = "skuId不能为空")
    @ApiModelProperty(value = "skuId", required = true)
    private Long skuId;

    @ApiModelProperty(value = "店铺ID，前端不用传该字段")
    private Long shopId;

    @NotNull(message = "商品个数不能为空")
    @ApiModelProperty(value = "商品个数", required = true)
    private Integer count;

    @ApiModelProperty(value = "商品是否勾选 true：勾选 ")
    private Boolean isCheck;
    
    一系列GET、SET、ToString方法。
}

@ApiModelProperty(value = "购物车ID", required = true)利用这个注解可以告诉前端开发人员该字段代表的含义以及是否必传。

常用注解

注解	作用
@Api	修饰整个类，描述Controller的作用
@ApiOperation	描述一个类的一个方法，或者说一个接口
@ApiParam	单个参数描述
@ApiModel	用对象来接收参数
@ApiProperty	用对象接收参数时，描述对象的一个字段
@ApiResponse	HTTP响应其中1个描述
@ApiResponses	HTTP响应整体描述
@ApiIgnore	使用该注解忽略这个API
@ApiError	发生错误返回的信息
@ApiImplicitParam	一个请求参数
@ApiImplicitParams	多个请求参数