swagger2的使用

一、前言

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

二、經歷的階段

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

三、新工具的使用-swagger2

第一次接觸到這個工具，只是聽別人說，不知道怎么使用，所以才有這個篇文檔，記錄一下自己的學習過程。

3.1、引入對應到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.2、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();
    }
}

四、swagger的基礎注解介紹

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

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

4.1、@Api修飾整個類，描述Controller的作用

4.2、@ApiOperation

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

可以添加的參數形式：@ApiOperation(value = “接口說明”, httpMethod = “接口請求方式”, response = “接口返回參數類型”, notes = “接口發布說明”）

4.3、@ApiParam單個參數描述

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

4.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.5、@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 +
                '}';
    }
}

 

 五、總結

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

 

自勉：

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