spring-boot-route（五）整合swagger生成接口文檔

目前，大多數公司都採用了先後端分離的開發模式，爲了解決先後端人員的溝通問題，後端人員在開發接口的時候會選擇使用swagger2來生成對應的接口文檔，swagger2提供了強大的頁面調試功能，這樣能夠有效解決先後端人員溝通難的問題。

下面咱們使用SpringBoot結合swagger2生成Restful API文檔。

一 搭建項目，引入依賴

新建一個spring-boot-swaager的項目，引入swaager2的依賴，因爲swagger2的ui不是很美觀，這裏將使用開源的swagger-bootstrap-ui作爲ui。

引入依賴

<!-- swaager2依賴 -->    
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- swaager2ui -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

項目中配置swagger相關信息

@Configuration
@EnableSwagger2
public class configuration {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.javatrip.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                // 標題
                .title("某某項目接口文檔")
                // 描述
                .description("swagger2接口文檔使用演示")
                // 版本
                .version("1.0")
                // 許可證
                .license("MIT")
                // 許可證地址
                .licenseUrl("www.xx.com")
                // 服務端地址
                .termsOfServiceUrl("https://www.cnblogs.com/zhixie/")
                // 聯繫信息
                .contact(new Contact("java旅途","https://www.cnblogs.com/zhixie/","binzh303@163.com"))
                .build();
    }
}

訪問路徑，查看生成效果

文章中使用的這個ui，接口文檔地址爲ip:port/doc.html，生成的文檔信息以下：

二 編寫Restful接口

新建實體類

@ApiModel("用戶實體類")
@Data
@NoArgsConstructor
@AllArgsConstructor
public class Person {
    @ApiModelProperty("姓名")
    private String name;
    @ApiModelProperty(value = "年齡")
    private int age;
}

新建Restful接口

@Api(tags = "用戶接口")
@RestController
@RequestMapping("person")
public class PersonController {

    @ApiOperation(value = "獲取用戶列表",notes = "根據name獲取用戶列表")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name",value = "用戶姓名",dataType = "String",required = true),
            @ApiImplicitParam(name = "age",value = "年齡",dataType = "int",required = true)
    })
    @GetMapping("/{name}")
    public Person getPerson(@PathVariable("name") String name,@RequestParam int age){
        return new Person(name,age);
    }

    @ApiOperation(value = "新增用戶",notes = "根據用戶實體類新增用戶")
    @ApiImplicitParam(name = "person",value = "用戶實體類",dataType = "Person",required = true)
    @PostMapping("add")
    public int addPerson(@RequestBody Person person){
        if(StringUtils.isEmpty(person)){
            return -1;
        }
        return 1;
    }

    @ApiOperation(value = "更新用戶信息",notes = "根據用戶實體更新用戶信息")
    @ApiImplicitParam(name = "person",value = "用戶實體類",dataType = "Person",required = true)
    @PutMapping("update")
    public int updatePerson(@RequestBody Person person){
        if(StringUtils.isEmpty(person)){
            return -1;
        }
        return 1;
    }

    @ApiOperation(value = "刪除用戶信息",notes = "根據用戶名刪除用戶信息")
    @ApiImplicitParam(name = "name",value = "用戶姓名",dataType = "String",required = true)
    @DeleteMapping("/{name}")
    public int deletePerson(@PathVariable(name = "name") String name){
        if(StringUtils.isEmpty(name)){
            return -1;
        }
        return 1;
    }
}

三 swagger文檔簡介

我就直接用圖來表示了，這樣看着也更加直觀

swagger2註解對應到文檔上的表現形式如上。swagger2支持在線調試，打開某個具體的接口，根據提示填寫對應的參數，點擊發送就可返回響應結果。

此是spring-boot-route系列的第五篇文章，這個系列的文章都比較簡單，主要目的就是爲了幫助初次接觸Spring Boot 的同窗有一個系統的認識。本文已收錄至個人github，歡迎各位小夥伴star！

github：https://github.com/binzh303/s...

點關注、不迷路

若是以爲文章不錯，歡迎關注、點贊、收藏，大家的支持是我創做的動力，感謝你們。

若是文章寫的有問題，請不要吝嗇，歡迎留言指出，我會及時覈查修改。

若是你還想更加深刻的瞭解我，能夠微信搜索「Java旅途」進行關注。回覆「1024」便可得到學習視頻及精美電子書。天天7:30準時推送技術文章，讓你的上班路不在孤獨，並且每個月還有送書活動，助你提高硬實力！