Spring boot 之自动生成API文档swagger2

目前解决API的方案一般有两种

1.编写文档接口。
2.利用一些现成的api系统。
3.如我一般想搞点特色的就自己写个api系统：http://api.zhaobaolin.vip/ ，这个还支持多用户。

但是无论哪一种，都逃不过一个麻烦事：如果代码有变化，必须手动维护文档，工作很忙的时候，根本没时间去折腾文档，忙着忙着就忘了，然后前端就经常架着把菜刀站我身后。。。

自从遇到swagger之后就如大旱逢甘露他乡遇故知洞房花烛夜金榜题名时.....

先用maven下载jar包：

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

然后在Application同级创建Swagger2类：

@Configuration
@EnableSwagger2
public class Swagger2 {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.test"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger2测试标题 请注意")
                .description("请记住我们亲爱的度娘：https://www.baidu.com/")
                .version("1.0")
                .build();
    }
}

Controller控制器：

@Api(value = "TestController", description = "测试数据服务 API", tags = "TestController")
@RestController
@RequestMapping(value = "/Test")
public class Test {

    @ApiOperation(value="请求的接口示例")
    @GetMapping(value = "/a")
    public String a() throws Exception{
        Child child = new Child();
        child.setAge("11");
        child.setName("码农");
        return child.toString();
    }

    @ApiOperation(value="输入参数接口示例")
    @PostMapping(value = "/c")
    public String c(Child child) throws Exception
    {
        if(null == child || null == child.getName() || null == child.getAge()){
            return "缺少参数";
        }
        return child.toString();
    }

    @ApiOperation(value="输入json接口示例")
    @PostMapping(value = "/d")
    public String d(@RequestBody @ApiParam(name = "child", value = "json fromat") Child child) throws Exception
    {
        if(null == child){
            return "参数错误";
        }
        return child.toString();
    }

实体类中required可标明是否必传：

public class Child{
    @ApiModelProperty(name = "name", value = "姓名", required = true)
    private String name;
    @ApiModelProperty(name = "age", value = "年龄", required = false)
    private String age;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getAge() {
        return age;
    }

    public void setAge(String age) {
        this.age = age;
    }

    @Override
    public String toString() {
        return "Child{" +
                "name='" + name + '\'' +
                ", age='" + age + '\'' +
                '}';
    }
}

访问 http://localhost:9000/swagger-ui.html# 端口换成自定义的

效果上图：

点击try it out 直接访问调试

必填字段如果不输入会被拦截

也可以json输入点击右边的Json框格式会自动进入输入框然后填值即可

感谢阅读

Spring boot 之自动生成API文档swagger2

猜你喜欢