Swagger和postman总结使用手册

Swagger使用背景：

使用Swagger可以直接生成接口文档，直接进行接口测试，不需要在postman中一个一个输入网址进行接口测试（麻烦）。

Swagger简单上手使用步骤（springboot项目）：

1.导入swagger依赖：（版本记得加）

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

 2.配置类(生成Swagger2文档对象)

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket adminApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2);
    }
}

3.在实体类和Controller层都可以添加Swagger注解（一些常用注解在下面），用来生成接口文档

运行项目后，在浏览器输入http://localhost:8080/swagger-ui.html即可看到文档界面，端口号需要根据你的tomcat服务器设置的端口号进行调整.

点击try it out，有参数输入参数，然后点击Execute即可

常用Swagger2注解

1.实体类常用注解

1.1类上@ApiModel()

//加在类上

@ApiModel(value="IntegralGrade对象", description="积分等级表")
public class IntegralGrade implements Serializable {...}

 value，description属性在接口文档中体现在response的Example Value|Model中（选中Model）

1.2属性上@ApiModelProperty()

@ApiModelProperty(value = "创建时间",example = "2021.01-01 00:00:00")
private LocalDateTime createTime;
@ApiModelProperty(value = "更新时间")
private LocalDateTime updateTime;

此注解加到实体类的属性上，对属性进行解释和可以添加示例格式example

同样，在接口文档中体现在response的Example Value|Model中（选中Example Value）

example:可以看到createTime属性的注解添加了example与updateTime的不同之处

value:体现在Model中

2.Controller类常用注解

2.1类上@Api()

@Api(tags = "积分等级管理")
public class AdminIntegralGradeController {...}

加个tag

 2.2方法上@ApiOperation()

@ApiOperation("积分登记列表")
@GetMapping("/list")
public List<IntegralGrade> listAll(){
    return integralGradeService.list();
}

@ApiOperation(value = "根据id删除积分列表数据",notes="逻辑删除积分列表数据")
@DeleteMapping("/remove/{id}")
public boolean removeById(@PathVariable Long id){
    return integralGradeService.removeById(id);
}

注解中一个参数时默认是value，可以省略value=

value属性体现在

notes属性体现在

2.3方法参数上@ApiParam()

@ApiOperation(value = "根据id删除积分列表数据",notes="逻辑删除积分列表数据")
@DeleteMapping("/remove/{id}")
public boolean removeById(
        @ApiParam(value = "数据id",example = "100",required=true)
        @PathVariable Long id){
    return integralGradeService.removeById(id);
}

value属性对参数进行解释

example属性可以给参数填一个默认值，方便测试，不需要每次填写

required属性可以标记属性是不是必须填

将接口文档分类显示

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket adminApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("admin")
                .select()
                .paths(Predicates.and(PathSelectors.regex("/admin/.*")))
                .build();
    }
    @Bean
    public Docket webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .select()
                .paths(Predicates.and(PathSelectors.regex("/api/.*")))
                .build();
    }
}

在配置类里再创建个Docket实例，并且根据groupName()给分类命名

通过PathSelectors.regex("/api/.*")筛选每个分类展示的接口http://localhost:8080/api/开头的url存到webApi分类中，另外admin分类同理（右上角选择分类接口）

 给接口文档添加描述信息

@Bean
public Docket adminApiConfig(){
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("admin")
            .apiInfo(adminApiInfo())
            .select()
            .paths(Predicates.and(PathSelectors.regex("/admin/.*")))
            .build();
}
private ApiInfo adminApiInfo(){
    return new ApiInfoBuilder()
            .title("srb后台管理系统-API文档")
            .description("本文档描述了srb后台管理系统接口")
            .version("1.0")
            .contact(new Contact("Yan Ping","...","826138753@qq.com"))
            .build();
}

 看看添加后的效果

显示到接口测试上方的内容

不同分类就不同写就好，比如另外个分类（admin和webApi）

@Bean
public Docket webApiConfig(){
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("webApi")
            .apiInfo(webApiInfo())
            .select()
            .paths(Predicates.and(PathSelectors.regex("/api/.*")))
            .build();
}
private ApiInfo webApiInfo(){
    return new ApiInfoBuilder()
            .title("srb-Web用户系统-API文档")
            .description("本文档描述了srb-Web用户系统接口")
            .version("1.0")
            .contact(new Contact("Yan Ping","...","826138753@qq.com"))
            .build();
}