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框 格式會自動進入輸入框  然后填值即可

 

感謝閱讀