swagger2的使用

1、前言

經歷了幾個不一樣的項目，在先後端分離的過程當中，接口文檔的重要性不言而喻，可是如何保持一個文檔的最新和代碼的一致性一直是一個問題，有時候定義了文檔，代碼中修改了一點小的東西，總會忘記同步修改文檔，時間長了，本身都比較蒙，還須要看一下代碼才能發現問題。

2、經歷的階段

第一次使用是阿里開源的RAP，可是領導說字段的順序跟他添加時不一致，他看到對應的文檔很差理業務，就直接放棄了這個工具（不知道後面的RAP2有沒有這個問題了），而後迴歸了他熟悉的Word文檔的模式，每次入參，說明含義，是否必需的，出參一大批，每次都要這麼搞，雖而後期代碼的明細很詳細，可是耗費的時間仍是很長的，好不誇張的說，40%的時間都是在寫文檔，最後敏捷開發快速迭代的時候，根本不敢以文檔說話了。

3、新工具的使用-swagger2

第一次接觸到這個工具，只是聽別人說，不知道怎麼使用，因此纔有這個篇文檔，記錄一下本身的學習過程。

3.一、引入對應到jar包

在pom文件中添加swagger2的包，引入相關的依賴，相關的pom文件能夠在mvnrepository中搜索相關的包。

    <!--swagger2的jar包-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!--引入視覺的樣式的UI-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

3.二、swagger2的配置文件

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(false)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("利用swagger構建api文檔")
                .description("簡單使用swagger2")
                .version("1.0")
                .build();
    }
}

4、swagger的基礎註解介紹

swagger經過註解生成接口文檔，包括接口名、請求方法、參數、返回信息的等等。

• @Api：修飾整個類，描述Controller的做用
• @ApiOperation：描述一個類的一個方法，或者說一個接口
• @ApiParam：單個參數描述
• @ApiModel：用對象實體來做爲入參
• @ApiProperty：用對象接實體收參數時，描述對象的一個字段
• @ApiResponse：HTTP響應其中1個描述
• @ApiResponses：HTTP響應總體描述
• @ApiIgnore：使用該註解忽略這個API
• @ApiError ：發生錯誤返回的信息
• @ApiImplicitParam：一個請求參數
• @ApiImplicitParams： 多個請求參數

4.一、@Api修飾整個類，描述Controller的做用

4.二、@ApiOperation

用於描述一個方法或者接口

能夠添加的參數形式：@ApiOperation(value = 「接口說明」, httpMethod = 「接口請求方式」, response = 「接口返回參數類型」, notes = 「接口發佈說明」）

4.三、@ApiParam單個參數描述

@ApiParam(required = 「是否必須參數」, name = 「參數名稱」, value = 「參數具體描述」,dateType="變量類型」,paramType="請求方式」）

4.四、@ApiImplicitParam 一個請求參數

@ApiImplicitParam(required = 「是否必須參數」, name = 「參數名稱」, value = 「參數具體描述」,dateType="變量類型」,paramType="請求方式」）

@ApiOperation(value = "根據用戶名獲取用戶的信息",notes = "查詢數據庫中的記錄",httpMethod = "POST",response = String.class)
@ApiImplicitParam(name = "userName",value = "用戶名",required = true,dataType = "String",paramType = "query")

4.五、@ApiImplicitParams 多個請求參數

參數和@ApiImplicitParam一致，只是這個註解能夠添加多個參數而已

@ApiImplicitParams({
            @ApiImplicitParam(name = "nickName",value = "用戶的暱稱",paramType = "query",dataType = "String",required = true),
            @ApiImplicitParam(name = "id",value = "用戶的ID",paramType = "query",dataType = "Integer",required = true)
    })
    public String getUserInfoByNickName(String nickName, Integer id) {
        return "1234";
    }

其他的都相似。

整個controller的代碼以下

@RestController
@RequestMapping("/swagger")
@Api(value = "swagger2的demo例子")
public class SwaggerController {
    @RequestMapping("/swagger")
    @ResponseBody
    @ApiOperation(value = "根據用戶名獲取用戶的信息",notes = "查詢數據庫中的記錄",httpMethod = "POST",response = String.class)
    @ApiImplicitParam(name = "userName",value = "用戶名",required = true,dataType = "String",paramType = "query")
    public String getUserInfo(String userName) {
        return "1234";
    }
    @RequestMapping(value = "/getuserinfobynickname",method = {RequestMethod.GET,RequestMethod.POST})
    @ResponseBody
    @ApiOperation(value = "根據用戶暱稱獲取用戶信息",notes = "查詢數據庫中的記錄")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "nickName",value = "用戶的暱稱",paramType = "query",dataType = "String",required = true),
            @ApiImplicitParam(name = "id",value = "用戶的ID",paramType = "query",dataType = "Integer",required = true)
    })
    public String getUserInfoByNickName(String nickName, Integer id) {
        return "1234";
    }
    @RequestMapping(value = "/getuserinfobyid",method = {RequestMethod.GET,RequestMethod.POST})
    @ResponseBody
    @ApiOperation(value = "根據用戶id獲取用戶信息",notes = "查詢數據庫中的記錄",httpMethod = "POST")
    public String getUserInfoById(@ApiParam(name = "nickName",value = "用戶的暱稱",required = true,defaultValue = "123-默認值")
                                          String nickName,@ApiParam(name = "id",value = "用戶ID",required = true) Integer id) {
        return "1234";
    }
    @RequestMapping(value = "/userregister",method = {RequestMethod.GET,RequestMethod.POST})
    @ResponseBody
    @ApiOperation(value = "register",notes = "註冊的實體類")
    public Register userRegister(Register register) {
        return register;
    }
}

相對應的接口文檔以下：

 

能夠直接進行測試

 

對應的實體說明：

@ApiModel(value = "用戶註冊的實體")
public class Register {
    @ApiModelProperty(name = "userName",notes = "用戶名",dataType = "String",required = true)
    private String userName;

    @ApiModelProperty(name = "nickName",notes = "用戶暱稱",dataType = "String",required = true)
    private String nickName;

    @ApiModelProperty(name = "age",notes = "用戶年齡",dataType = "int",required = true)
    private int age;
    public String getUserName() {
        return userName;
    }

    public void setUserName(String userName) {
        this.userName = userName;
    }

    public String getNickName() {
        return nickName;
    }

    public void setNickName(String nickName) {
        this.nickName = nickName;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }
    @Override
    public String toString() {
        return "Register{" +
                "userName='" + userName + '\'' +
                ", nickName='" + nickName + '\'' +
                ", age=" + age +
                '}';
    }
}

 

 5、總結

學習過程就是一個熟悉的過程

 

自勉：

接觸新事物，學習的過程就是本身的積攢過程，可能簡單或者有錯誤，可是誰不是一個學習積攢的過程那，沒有所謂的天才，只有拼搏和努力，只要肯積攢，總有變大神的一天。