使用swagger优雅书写api文档

书写和前端对接的api文档十分痛苦，工作中经常会有下面场景

• 接口文档地址分散
• 接口文档相对代码更新滞后
• 前端同事找不到对接的后端同事
• 懒得写
• 其他
  swagger框架很好的解决其中的一些问题。

先上效果

这里出现了一个类似接口文档的web界面，里面有文档的title

xx系统接口文档

文档的描述

swagger 接口测试

以及一些作者信息

image.png

点开

demo-controller:接口测试

可以看到一个接口

GET /test/person

还有一个类似postman的界面。里面有request的parameter的描述，response结构的描述。

image.png

我们随便输入一个name的value，然后try it out

image.png

出现了这个请求的response

{
  "code": "000",
  "msg": "success",
  "data": {
    "name": "鸡熟了",
    "age": 29
  }
}

这样，一个非常简单的接口调试就完成了。

下面我们看看代码是怎么实现的。

首先新建一个springboot 的web应用

然后引入swagger的maven依赖

<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>

配置swagger

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Configuration
    public class SwaggerDocket {

        @Bean
        public Docket docket() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
//                    .pathMapping("/")
                    .select() // 选择那些路径和api会生成document
//                    .apis(RequestHandlerSelectors.any())// 对所有api进行监控
                    //不显示错误的接口地址
                    .paths(Predicates.not(PathSelectors.regex("/error.*")))//错误路径不监控
                    .paths(PathSelectors.any())// 对根下所有路径进行监控
                    .build();
        }

        private ApiInfo apiInfo() {
            return new ApiInfoBuilder().title("xx系统接口文档")
                    .contact(new Contact("鸡熟了", "http://xxx.blog.com", "xxx@gmail.com"))
                    .description("swagger 接口测试")
                    .termsOfServiceUrl("NO terms of service")
                    .license("The Apache License, Version 2.0")
                    .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                    .version("v1.0")
                    .build();
        }
    }
}

随便定义几个对象

@Data
@ApiModel("通用response")
public class DemoResp<T> {
    @ApiModelProperty("返回code")
    private String code;
    @ApiModelProperty("返回msg")
    private String msg;
    @ApiModelProperty("返回data")
    private T data;

    public static <T> DemoResp<T> success(T data) {
        DemoResp<T> resl = new DemoResp<>();
        resl.setCode("000");
        resl.setMsg("success");
        resl.setData(data);
        return resl;
    }
}

@Data
@Builder
@ApiModel("人")
public class Person {
    @ApiModelProperty("名字")
    private String name;
    @ApiModelProperty("年龄")
    private Integer age;
}

随便写一个REST接口的controller

@RestController
@RequestMapping("/test")
@Api(description = "测试接口")
public class DemoController {

    @GetMapping("/person")
    @ApiOperation("根据用户名获取用户信息")
    public DemoResp<Person> getPerson(@RequestParam("name") @ApiParam("名字") String name) {
        return DemoResp.success(Person.builder().name("鸡熟了").age(29).build());
    }
}

D大的网友已经发现，文档里面对应的信息，全是用注解的方式，书写在

• controller类
• 方法
• 对象

上面，所有用注解标注的都会在文档页面显示。
默认swagger生成的文档web地址：

http://xxxxxxx/swagger-ui.html#/

swagger文档会随着应用一起启动。
这样，只需要把这个url发给前端同事就行了。当接口有变更的时候，修改对应的注解，应用启动之后就会自动生效。
当然swagger还有更详细，更丰富的玩法。可以自行研究。

完