springmvc+swagger構建Restful風格文件

　　本次和大家分享的是java方面的springmvc來構建的webapi介面+swagger文件；上篇文章分享.net的webapi用swagger來構建文件，因為有朋友問了為啥.net有docpage文件你還用swagger，這裡主要目的是讓介面文件統一，當操作多種開發語言做介面時，如果有統一風格的api文件是不是很不錯；還有就springcloude而言，微服務如果有很多的話，使用swagger自動根據服務serverid來載入api文件是很方便的。swagger設定比較簡單，為了今後查詢資料和使用方便故此記錄下

• 準備工作
• 快速構建api文件
• 常用的細節

1. 過濾預設錯誤api
2. 新增授權token列
3. 新增上傳檔案列

準備工作

　　首選需要一個springmvc專案，這裡我用的是springboot+maven來快速構建， 要使用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>

　　然後建立一個UserController，然後再定義個Login的Action，定義請求和響應實體，由於api介面需要對請求和響應屬性列做 文字描述，並且上面我們在專案中加了swagger包，因此以直接在實體和Action使用特性來增加具體文字描述：

@RestController
@Api(tags = "會員介面")
public class UserController {

    @PostMapping("/login")
    @ApiOperation(value = "登入")
    public LoginRp login(@RequestBody LoginRq rq) {
        LoginRp rp = new LoginRp();

        if (rq.getUserName().isEmpty() || rq.getUserPwd().isEmpty()) {
            rp.setCode(EmApiCode.登入賬號或密碼不能為空.getVal());
            return rp;
        }

        if (rq.getUserName().equals("shenniu001") && rq.getUserPwd().equals("123")) {
            rp.setCode(EmApiCode.成功.getVal());

            rp.setToken(UUID.randomUUID().toString());
        } else {
            rp.setCode(EmApiCode.失敗.getVal());
        }
        return rp;
    }

}

　　請求和響應實體類：

@ApiModel
public class LoginRq implements Serializable{

    private static final long serialVersionUID = -158328750073317876L;

    @ApiModelProperty(value = "登入賬號")
    private String userName;

    @ApiModelProperty(value = "登入密碼")
    private String userPwd;

}

@ApiModel
public class LoginRp extends BaseRp implements Serializable {
    private static final long serialVersionUID = -1486838360296425228L;

    @ApiModelProperty(value = "授權token")
    private String token;

    public String getToken() {
        return token;
    }

    public void setToken(String token) {
        this.token = token;
    }
}

　　註解簡單說明：

　　@Api：同一類介面的總描述，一般用於Controller標記

　　@ApiOperation(value = "登入")：在Action上標記，描述這個Action介面具體幹什麼

　　@ApiModel：請求響應實體類class上的標記

　　@ApiModelProperty(value = "登入賬號")：請求響應屬性上的標記，用來描述該屬性具體說明

快速構建api文件

　　準備做完後要生成文件，還需要自定義兩個封裝類，如下Swagger2類：

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                //過濾預設錯誤api
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
                .build()
                .apiInfo(apiInfo());
    }

    //常用的細節
    //過濾指定的action
    //新增授權token列
    //新增上傳檔案列
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("開車介面文件")
                .description("該文件只允許我使用")
                //版本
                .version("0.0.0.1")
                .contact("作者：841202396@qq.com")
                .build();
    }
}

　　這個類主要初始化一些全域性文件的說明和版本並且構架api文件；上面是生成文件，但是具體文件資料來源用從swagger的SwaggerResourcesProvider中來，因此自定義的DocumentationConfig類實現SwaggerResourcesProvider介面，如下：

@Component
@Primary
public class DocumentationConfig implements SwaggerResourcesProvider {
    @Override
    public List<SwaggerResource> get() {
        List resources = new ArrayList<>();
        resources.add(swaggerResource("開車介面api", "/v2/api-docs", "0.0.0.1"));
        resources.add(swaggerResource("坐車介面api", "/v2/api-docs", "0.0.0.1"));
        return resources;
    }

    private SwaggerResource swaggerResource(String name, String location, String version) {
        SwaggerResource swaggerResource = new SwaggerResource();
        swaggerResource.setName(name);
        swaggerResource.setLocation(location);
        swaggerResource.setSwaggerVersion(version);
        return swaggerResource;
    }
}

　　主要載入文件的資料來源，資料來源主要通過 resources.add(swaggerResource("坐車介面api", "/v2/api-docs", "0.0.0.1")) 新增，倘若你想新增其他api介面源就可以在這裡進行配置，直接把/v2/api-docs改成你的url就行，這個地方也是springcloud微服務api新增的入口；當編碼完成後我們來看看效果：

　　

　　能成功載入出我們的login介面，而且有一些說明性的文字；再來看看我們請求和響應的引數是否有說明：

　　

　　請求和響應都有了相應的說明，是不是挺簡單；

常用的細節

　　1.過濾預設錯誤api

　　由於springmvc封裝有錯誤的controller，因此swagger也會把這個展示出來，因為是掃描的所有controller來展示swagger文件的，故此我們需要遮蔽這些對於對接方沒用的介面；這裡通過設定paths的不匹配就行了，以下程式碼：

//過濾預設錯誤api
paths(Predicates.not(PathSelectors.regex("/error.*")))

　　2.新增授權token列

　　對於介面驗證來說通常需要個token並且放在header裡面，這裡我們直接在swagger上增加一個顯示的token，只需要在build之前增加一個header引數：

@Bean
    public Docket createRestApi() {

        List<Parameter> pars = new ArrayList<>();
        //新增授權token
        ParameterBuilder tokenPar = new ParameterBuilder();
        tokenPar.name("token").description("授權token 注：登入不需要填，只有post方式的介面必填").
                modelRef(new ModelRef("string")).
                parameterType("header").required(false).build();
        pars.add(tokenPar.build());

        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
                .build()
                .globalOperationParameters(pars)
                .apiInfo(apiInfo());
   }

　　這個時候每個action介面文件塊中都會增加一個token列，type是header型別：

　　

　　3.新增上傳檔案列

　　通常api介面都包含一個公共上傳介面，為了讓swagger文件更方便，我們需要讓她支援下上傳；首先這樣定義一個上傳介面：

@PostMapping(value = "/upload",headers = "content-type=multipart/form-data")
    @ApiOperation(value = "上傳")
    public BaseRp upload(@ApiParam(value = "上傳的檔案",required = true) @RequestBody MultipartFile file) {
        BaseRp rp = new BaseRp();

        rp.setMessage("上傳檔名："+file.getOriginalFilename());

        return rp;
    }

　　其他就不用再設定了，僅僅如此執行後效果：

　　

　　咋們點選“選擇檔案”測試下上傳，點選try能夠得到如下成功執行的效果圖：