写一篇通俗易懂的swagger2操作技术文

swagger2是什么

是后端提供文档的工具库。

如何使用

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

例子

@ApiModel 用于entity实体类上的

@ApiModelProperty 用于entity实体类属性上的

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;


@ApiModel(value = "用户实体",description = "用户实体")
@Data
public class User {

    @ApiModelProperty(value = "主键")
    private int id;

    @ApiModelProperty(value = "姓名")
    private String name;

    @ApiModelProperty(value = "年龄")
    private int age;

    @ApiModelProperty(value = "地址")
    private String address;

}

@Api 用于Controller类上的

@ApiOperation用于Controller类方法上的

@RestController
@RequestMapping("/user")
@Api(tags = "用户控制器")
public class UserController {

    @GetMapping("/getUsers")
    @ApiOperation(value = "查询所有用户",notes = "查询所有用户信息")
    public List<User> getAllUsers(){
        User user = new User();
        user.setId(100);
        user.setName("liuyun");
        user.setAge(20);
        user.setAddress("bj");
        ArrayList<User> list = new ArrayList<>();
        list.add(user);
        return list;
    }
}

@ApiImplicitParams 用于方法数组上的

@ApiImplicitParam用于方法参数上的

@ApiImplicitParams({
	@ApiImplicitParam(name = "pageNum", value = "页码", 
                     required = true, type = "Integer"),
	@ApiImplicitParam(name = "pageSize", value = "每页条数", 
                     required = true, type = "Integer"),
})
@ApiOperation(value = "分页查询菜单信息")
@GetMapping(value = "page/{pageNum}/{pageSize}")
public String findByPage(@PathVariable Integer pageNum,
                         @PathVariable Integer pageSize) {
    return "OK";
}

@ApiImplicitParam(name = “pageNum”, value = “页码”, required = true, type = “Integer”)

还需要一个SwaggerAutoConfiguration ,直接复制即可

@Configuration
@EnableSwagger2
public class SwaggerAutoConfiguration {
    @Bean
    public Docket createRestApi1() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()).groupName("用户接口组")
                .select()
                //为当前包路径
                .apis(RequestHandlerSelectors.basePackage("cn.liuyun.controller.user"))
                .build();
        return docket;
    }

    @Bean
    public Docket createRestApi2() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()).groupName("菜单接口组")
                .select()
                //为当前包路径
                .apis(RequestHandlerSelectors.basePackage("cn.liuyun.controller.menu"))
                .build();
        return docket;
    }
    
    //构建 api文档的详细信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("API接口文档")
                //创建人
                .contact(new Contact("梦中一夜下江南", "https://blog.csdn.net/v2810769", ""))
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }
}