SpringBoot整合Swagger

SpringBoot整合Swagger

1.Swagger简介

• Swagger官网介绍
• 使用Swagger开源和专业工具集为用户、团队和企业简化API开发
• 简单来说就是生成后端开发的API接口文档，自定义表明参数，返回值以及方法说明等信息，多用于交付前端，测试以及甲方。协作开发适用于前后端分离项目

2.SpringBoot整合Swagger

2.1 创建SpringBoot项目 ，添加Swagger依赖

​ 2.1.1 Maven仓库地址

• SpringFox Swagger2
• SpringFox Swagger UI

        <!--Swagger-UI API文档生产工具-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>

2.2编写配置类-SwaggerConfig，自定义API文档信息

/**
 * Swagger2API文档的配置
 */
@Configuration
@EnableSwagger2    //开启Swagger注解
public class Swagger2Config {


    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("分组名-A")
                .select()
                //为当前包下controller生成API文档     参数为本地controller的包路径
                .apis(RequestHandlerSelectors.basePackage("xxx.xxx.contorller"))
                //为有@Api注解的Controller生成API文档
//                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                //为有@ApiOperation注解的方法生成API文档
//                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SwaggerUI演示")    //标题名称
                .description("暴漏接口API-UI界面")   //文档描述
                //服务条款URL
                .termsOfServiceUrl("http://localhost:8081/swagger-ui.html")
                .version("1.0")
                .build();
    }
}

3.Swagger常用注解

• @Api()
• @ApiOperation()
• @ApiParam()
• @ApiModel()
• @ApiModelProperty()
• @ApiIgnore()

Swagger常用注解	说明
@Api(tags = “xxx模块说明”)	作用在模块类上
@ApiOperation(“xxx接口说明”)	作用在接口方法上
@ApiModel(“xxxPOJO说明”)	作用在模型类上：如VO、BO
@ApiModelProperty(value = “xxx属性说明”,hidden = false)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam(“xxx参数说明”)	作用在参数、方法和字段上，类似@ApiModelProperty

3.1 @Api()

@Api(tags = "test测试类" , description = "API测试接口文档")
// 作用于类 表示标识这个类是swagger的资源，可以自定义swaggerAPI文档信息
@RestController
public class TestController {
    public xxx  xxx(){
        xxx;
    }
}

3.2 @ApiOperation()

@Autowired
private itemService itemService;

@GetMapping("/test")
//作用于方法 表示一个http请求的操作 可以定义文档信息
@ApiOperation("测试接口方法")
public Item TestMethod(@RequestParam Integer id){
    return itemService.selectById(id);
}

3.3 @ApiParam()

public Item TestMethod(@ApiParam("商品编号")  //作用于方法参数  表示对参数的添加元数据（说明或是否必填等）
                       @RequestParam Integer id){
    return itemService.selectById(id);
}

3.4 @ApiModel()

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel("商品实体类")
//作用于实体类  表示对类进行说明，用于参数用实体类接收
public class Item implements Serializable {
		xxx;
		xxx;
}

3.5 @ApiModelProperty()

public class Item implements Serializable {
    private Integer id;

    @ApiModelProperty("商品名称")
    //作用于实体类的属性 表示对model属性的说明或者数据操作更改
    private String itemName;

    @ApiModelProperty("商品价格")
    private BigDecimal price;

    @ApiModelProperty("商品数量")
    private String amount;

}

3.6 @ApiIgnore()

//@ApiIgnore()作用于类，方法，方法参数 表示这个方法或者类被忽略

4.添加注解自定义生成API文档

//controller接口
@Api(tags = "test测试类", description = "API测试接口文档")
@RestController
public class TestController {
    @Autowired
    private itemService itemService;

    @GetMapping("/test")
    //说明是什么方法(可以理解为方法注释)
    @ApiOperation("测试接口方法")
    public Item TestMethod(@ApiParam("商品编号") @RequestParam Integer id){
        return itemService.selectById(id);
    }
}

//实体类
@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel("商品实体类")
public class Item implements Serializable {
    private Integer id;

    @ApiModelProperty("商品名称")
    private String itemName;

    @ApiModelProperty("商品价格")
    private BigDecimal price;

    @ApiModelProperty("商品数量")
    private String amount;

}

效果展示： 访问地址：http://localhost:8080/swagger-ui.html

访问地址根据服务启动的端口保证一致

5.扩充：接口文档UI样式

我们可以导入不同的依赖实现不同的UI风格：

1、swagger默认的 访问 http://localhost:8080/swagger-ui.html

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

2、bootstrap-ui 访问 http://localhost:8080/doc.html

<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.1</version>
</dependency>

3. Layui-ui 访问 http://localhost:8080/docs.html

<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
   <groupId>com.github.caspar-chen</groupId>
   <artifactId>swagger-ui-layer</artifactId>
   <version>1.1.3</version>
</dependency>

4. mg-ui 访问 http://localhost:8080/document.html

<!-- 引入swagger-ui-layer包 /document.html-->
<dependency>
   <groupId>com.zyplayer</groupId>
   <artifactId>swagger-mg-ui</artifactId>
   <version>1.0.6</version>
</dependency>