書寫和前端對(duì)接的api文檔十分痛苦，工作中經(jīng)常會(huì)有下面場(chǎng)景

• 接口文檔地址分散
• 接口文檔相對(duì)代碼更新滯后
• 前端同事找不到對(duì)接的后端同事
• 懶得寫
• 其他
  swagger框架很好的解決其中的一些問題其馏。

先上效果

這里出現(xiàn)了一個(gè)類似接口文檔的web界面拂封，里面有文檔的title

xx系統(tǒng)接口文檔

文檔的描述

swagger 接口測(cè)試

以及一些作者信息

image.png

點(diǎn)開

demo-controller:接口測(cè)試

可以看到一個(gè)接口

GET /test/person

還有一個(gè)類似postman的界面势誊。里面有request的parameter的描述播赁，response結(jié)構(gòu)的描述。

image.png

我們隨便輸入一個(gè)name的value语稠，然后try it out

image.png

出現(xiàn)了這個(gè)請(qǐng)求的response

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

這樣漆弄，一個(gè)非常簡(jiǎn)單的接口調(diào)試就完成了睦裳。

下面我們看看代碼是怎么實(shí)現(xiàn)的。

首先新建一個(gè)springboot 的web應(yīng)用

然后引入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會(huì)生成document
//                    .apis(RequestHandlerSelectors.any())// 對(duì)所有api進(jìn)行監(jiān)控
                    //不顯示錯(cuò)誤的接口地址
                    .paths(Predicates.not(PathSelectors.regex("/error.*")))//錯(cuò)誤路徑不監(jiān)控
                    .paths(PathSelectors.any())// 對(duì)根下所有路徑進(jìn)行監(jiān)控
                    .build();
        }

        private ApiInfo apiInfo() {
            return new ApiInfoBuilder().title("xx系統(tǒng)接口文檔")
                    .contact(new Contact("雞熟了", "http://xxx.blog.com", "xxx@gmail.com"))
                    .description("swagger 接口測(cè)試")
                    .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();
        }
    }
}

隨便定義幾個(gè)對(duì)象

@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;
}

隨便寫一個(gè)REST接口的controller

@RestController
@RequestMapping("/test")
@Api(description = "測(cè)試接口")
public class DemoController {

    @GetMapping("/person")
    @ApiOperation("根據(jù)用戶名獲取用戶信息")
    public DemoResp<Person> getPerson(@RequestParam("name") @ApiParam("名字") String name) {
        return DemoResp.success(Person.builder().name("雞熟了").age(29).build());
    }
}

D大的網(wǎng)友已經(jīng)發(fā)現(xiàn)撼唾，文檔里面對(duì)應(yīng)的信息推沸，全是用注解的方式，書寫在

• controller類
• 方法
• 對(duì)象

上面券坞，所有用注解標(biāo)注的都會(huì)在文檔頁(yè)面顯示鬓催。
默認(rèn)swagger生成的文檔web地址：

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

swagger文檔會(huì)隨著應(yīng)用一起啟動(dòng)。
這樣恨锚，只需要把這個(gè)url發(fā)給前端同事就行了宇驾。當(dāng)接口有變更的時(shí)候，修改對(duì)應(yīng)的注解猴伶，應(yīng)用啟動(dòng)之后就會(huì)自動(dòng)生效课舍。
當(dāng)然swagger還有更詳細(xì)，更豐富的玩法他挎◇菸玻可以自行研究。

完