SpringBoot-11-Swagger

OpenAPI规范(OpenAPI Specification简称OAS)是Linux基金会的一个项目,试图通过定义一种用来描述API格式或API定义的语言,来规范RESTful服务开发过程。Swagger是目前最瘦欢迎的OpenAPI规范API开发工具框架,支持从设计和文档到测试和部署的整个API生命周期的开发。

Swagger可以随项目生成强大的RESTful API文档,减少开发人员的工作量(不用自己写API接口文档了)。使用Swagger,只需要在代码中添加一些注解即可生成API接口文档,便于同步更新API文档的说明。另外生成API文档页面带有测试功能,可以用来调试每个RESTful API接口。

2020.07出了Swagger3.0,但是目前文档和网上教程都不太完善,后续学有余力再研究一下3.0,具体的资料都在官方github

Swagger 2.x基本使用

3.0已经有starter了,导一个就可以,但是2.9.2还需要导两个依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

然后需要一个配置类,用来配置一些基本信息,格式基本是固定的:

@EnableSwagger2
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))//扫描带有ApiOperation注解的方法
                .paths(PathSelectors.any())
                .build();
    }

    // 创建api的基本信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("用户账号接口文档")
                .description("集成Swagger2构建Restful APIS")
                .termsOfServiceUrl("http://www.xxxxx.com/")
                .contact(new Contact("youkee", "", "xdutao@foxmail.com"))
                .license("采用 Apache 2.0开源许可证")
                .version("1.0.0")
                .build();
    }
}

这么看可能有点一头雾水,但是现在只配置这一点东西,然后打开http://localhost:8080/swagger-ui.html,看一下页面上的内容,就大概知道了:

SpringBoot-11-Swagger

等于说这个配置类在配接口文档页面的基本信息和一些扫描规则

下面写一个简单的pojo User和UserController

@Data
public class User {
    private Integer id;
    private String name;
}
@Controller
public class UserController {

    private Integer count = 1000;

    @GetMapping("/users")
    public ModelAndView getUserCount() {
        ModelAndView modelAndView = new ModelAndView();
        modelAndView.addObject("userCount", count);
        modelAndView.setViewName("userCount");
        return modelAndView;
    }


    @GetMapping("/users/{id}")
    public @ResponseBody User getUserById(@PathVariable("id") Integer id) {
        User user = new User();
        user.setId(id);
        user.setName("bob" + id);
        return user;
    }

    @PostMapping("/users/{id}/{name}")
    public ModelAndView insertUser(@PathVariable("id") Integer id,
                                   @PathVariable("name") String name) {
        ModelAndView modelAndView = new ModelAndView();
        User user = new User();
        user.setId(id);
        user.setName(name);
        modelAndView.addObject("user", user);
        count++;
        modelAndView.addObject("userCount", count);
        modelAndView.setViewName("insertSuccess");
        return modelAndView;
    }
}

但是在没有任何注解的情况下,Swagger是没办法帮你生成这些方法的接口文档的,下面先列举一些注释的用途,然后再结合代码看一下具体的作用。列举的注解和属性都不是特别全的,可以点进源码看一下,代码的注释都说的非常清楚;或者看官网文档,不过官方文档也已经更新成3.0的用法了,后续再好好学一下。

  • @Api:用在类上,说明该类的作用

  • @ApiOperation:用在方法上,说明方法的作用

  • @ApiImplicitParams:用在方法上包含一组参数说明

  • @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面

    • paramType:参数放在哪个地方

      • header --> 请求参数的获取@RequestHeader
      • query --> 请求参数的获取@RequstParam
      • path --> 请求参数的获取@PathVariable
      • body --> 请求参数的获取@RequestBody
      • form --> form-data获取参数
    • name:参数名

    • dataType:参数类型

    • required:参数是否必须传

    • value:参数的意思

    • defaultValue:参数的默认值

  • @ApiResponses:用于表示一组响应

  • @ApiResponse:用在@ApiResponses注解中,用于表达一个错误的响应信息

    • code:数字,比如400,404
    • message:信息,例如“请求参数不合法”
    • response:抛出异常的类
  • @ApiIgnore:使用该注解忽略这个API,不在页面上显示

  • @ApiModel:描述一个Model的信息

  • @ApiModel:描述一个Model的属性

先对User改造一下:

@Data
@ApiModel(value = "User", description = "用户对象")
public class User {
    @ApiModelProperty(value = "用户ID", example = "1001")
    private Integer id;
    @ApiModelProperty(value = "用户姓名", example = "张三")
    private String name;
}

然后controller的代码是改动最多的,需要加很多注解:

@Controller
@Api(tags = "用户控制层,负责处理用户相关请求")
public class UserController {

    private Integer count = 1000;

    @ApiOperation(value = "获取用户总人数", notes = "查询数据库中所有用户")
    @ApiResponses({
            @ApiResponse(code = 200, message = "请求成功"),
            @ApiResponse(code = 401, message = "请求路径没有相应权限"),
            @ApiResponse(code = 403, message = "请求路径呗隐藏,不能访问"),
            @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对"),
            @ApiResponse(code = 405, message = "请求方法不支持")
    })
    @GetMapping("/users")
    public ModelAndView getUserCount() {
        ModelAndView modelAndView = new ModelAndView();
        modelAndView.addObject("userCount", count);
        modelAndView.setViewName("userCount");
        return modelAndView;
    }


    @ApiOperation(value = "查询用户", notes = "根据路径中的id在数据库中查询用户")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "path", name = "id", value = "用户ID", dataType = "Integer")
    })
    @ApiResponses({
            @ApiResponse(code = 200, message = "请求成功"),
            @ApiResponse(code = 400, message = "缺少必要的请求参数"),
            @ApiResponse(code = 401, message = "请求路径没有相应权限"),
            @ApiResponse(code = 403, message = "请求路径被隐藏,不能访问"),
            @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对"),
            @ApiResponse(code = 405, message = "请求方法不支持")
    })
    @GetMapping("/users/{id}")
    public @ResponseBody User getUserById(@PathVariable("id") Integer id) {
        User user = new User();
        user.setId(id);
        user.setName("bob" + id);
        return user;
    }


    @ApiOperation(value = "插入用户", notes = "根据路径中的id,name创建用户并插入数据库")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "path", name = "id", value = "用户ID", dataType = "Integer"),
            @ApiImplicitParam(paramType = "path", name = "name", value = "用户姓名", dataType = "String")
    })
    @ApiResponses({
            @ApiResponse(code = 200, message = "请求成功"),
            @ApiResponse(code = 400, message = "缺少必要的请求参数"),
            @ApiResponse(code = 401, message = "请求路径没有相应权限"),
            @ApiResponse(code = 403, message = "请求路径被隐藏,不能访问"),
            @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对"),
            @ApiResponse(code = 405, message = "请求方法不支持")
    })
    @PostMapping("/users/{id}/{name}")
    public ModelAndView insertUser(@PathVariable("id") Integer id,
                                   @PathVariable("name") String name) {
        ModelAndView modelAndView = new ModelAndView();
        User user = new User();
        user.setId(id);
        user.setName(name);
        modelAndView.addObject("user", user);
        count++;
        modelAndView.addObject("userCount", count);
        modelAndView.setViewName("insertSuccess");
        return modelAndView;
    }
}

看着比较多,但是对应着生成的接口文档看一下,就比较清晰了:

SpringBoot-11-SwaggerSpringBoot-11-SwaggerSpringBoot-11-Swagger

剩下的ModelAndView是因为返回方法中返回的有,所以也当Model处理了,没有@ApiModel注解,所以内容也比较乱。

SpringBoot-11-Swagger
上一篇:简单介绍下 springMVC 和 struts2 的区别有哪些?


下一篇:获取元素在文档中的位置------getBoundingClientRect和循环获取位置