24.从零开始学springboot-swagger2文档自动生成

前言

在软件开发周期中，我们写完代码常常还要写文档，一方面给调用方提供调用文档，一方面也能归档。
其实，做开发的对于写文档这件事很是呵呵，占用了至少40%的开发时间，而且每当代码有调整，还得记得去修改对应的文档。
那么，springboot有没有哪种方法可以帮助我们自动生成文档呢，这样能解决我们开发人员的痛点。
本章，我们就来介绍Swagger2这个东东，使用后你会爱上它的。

好处：

• 自动生成文档，代码写完，文档即完成
• 无需复杂的配置，简单易用

Swagger2常用注解

@Api()用于类；
表示标识这个类是swagger的资源

tags：表示说明
value：也是说明，可以使用tags替代

@Api(value="测试controller",tags={"测试接口"})
@RestController
public class Swagger2Controller {
}

@ApiOperation()用于方法；
表示一个http请求的操作

value：用于方法描述
notes： 用于提示内容
tags： 可以重新分组

@ApiOperation(value="获取列表",tags={"获取列表信息"},notes="列表")
@GetMapping("/getList")
public int getList() {
      return 1;
}

@ApiParam()用于方法，参数，字段说明；
表示对参数的添加元数据（说明或是否必填等）

name：参数名
value：参数说明
required：是否必填

@ApiOperation("查询2")
@GetMapping("/query")
public Long query(@ApiParam(name = "id", value = "id", required = true) Long id, @ApiParam(name = "name", value = "名称", required = true) String name) {
        return id;
    }

@ApiModel()用于类
表示对类进行说明，用于参数用实体类接收
value：表示对象名
description：描述

@ApiModel(value="Person对象",description="用户对象Person")
public class Person {
}

@ApiModelProperty()用于方法，字段
表示对model属性的说明或者数据操作更改
value：字段说明
name：重写属性名字
dataType：重写属性类型
required：是否必填
example：举例说明
hidden：隐藏

public class Person {
@ApiModelProperty(value = "名称", name = "name", example = "张三", required = true)
    private String name;
}

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

    @ApiIgnore()
    @ApiOperation("隐藏")
    @ApiParam(name = "Person对象", value = "传入json格式", required = true)
    @GetMapping("/hideFunc")
    public Person hideFunc(@RequestBody Person person) {
        return person;
    }

@ApiImplicitParam() 用于方法
表示单独的请求参数
name：参数ming
value：参数说明
dataType：数据类型
paramType：参数类型
example：举例说明

    @ApiOperation("详情")
    @ApiImplicitParam(name = "id", value = "id", required = true, dataType = "long", paramType = "query")
    @GetMapping("/getInfoById")
    public Long getInfoById(Long id) {
        return id;
    }

@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

    @ApiOperation("查询")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "id", dataType = "long", paramType = "query"),
            @ApiImplicitParam(name = "name", value = "名称", dataType = "string", paramType = "query", example = "张三")
    })
    @GetMapping("/queryList")
    public Long queryList(Long id, String name) {
        return id;
    }

更多注解及使用方式请查看

官方WIKI

Swagger2配置

@Configuration
@EnableSwagger2
public class Swagger2Config {

    //http://127.0.0.1:8080/swagger-ui.html#/


    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(false)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger自动构建文档")
                .description("简单使用swagger2")
                .version("1.0.0")
                .build();
    }
}

文档查看地址

http://127.0.0.1:8080/swagger-ui.html#/

项目地址

https://github.com/MrCoderStack/SpringBootDemo/tree/master/sb-swagger2

请关注我的订阅号