關於Swagger2和SpringBoot整合使用

1、爲何要使用Swagger2

現代化的研發組織架構中，一個研發團隊基本包括了產品組、後端組、前端組、APP端研發、 測試組、 UI組等，各個細分組織人員各司其職，共同完成產品的全週期工做。如何進行組織架構內的有效高效溝通就顯得尤爲重要。其中，如何 構建一份合理高效的接口文檔更顯重要。

2、經常使用的註解

3、使用步驟

一、導入依賴

<!-- swagger2 配置 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.4.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.4.0</version>
        </dependency>

二、編寫Swagger2的配置類

@Configuration
@EnableSwagger2
public class Swagger2 {

    /**
     * @Description:swagger2的配置文件，這裏能夠配置swagger2的一些基本的內容，好比掃描的包等等
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.imooc.controller"))
                .paths(PathSelectors.any()).build();
    }

    /**
     * @Description: 構建 api文檔的信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 設置頁面標題
                .title("使用swagger2構建短視頻後端api接口文檔")
                // 設置聯繫人
                .contact(new Contact("imooc-Nathan", "http://www.imooc.com", "scau_zns@163.com"))
                // 描述
                .description("歡迎訪問短視頻接口文檔，這裏是描述信息")
                // 定義版本號
                .version("1.0").build();
    }
}

訪問 http://localhost:8080/swagger-ui.html

三、配置某個Controller

@RestController
@RequestMapping("/video")
@Api(value = "視頻相關業務的接口",tags = {"視頻相關業務的controller"})
public class VideoController {
}

四、配置某個接口方法

@ApiOperation(value = "上傳視頻",notes = "上傳視頻的接口")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userId", value = "用戶id", required = true, dataType = "String", paramType = "form"),
            @ApiImplicitParam(name = "bgmId", value = "背景音樂id", required = false, dataType = "String", paramType = "form"),
            @ApiImplicitParam(name = "videoSeconds", value = "背景音樂的播放長度", required = true, dataType = "String", paramType = "form"),
            @ApiImplicitParam(name = "videoWidth", value = "視頻寬度", required = true, dataType = "String", paramType = "form"),
            @ApiImplicitParam(name = "videoHeight", value = "視頻高度", required = true, dataType = "String", paramType = "form"),
            @ApiImplicitParam(name = "desc", value = "視頻描述", required = false, dataType = "String", paramType = "form")
    })
    @PostMapping(value = "/upload", headers = "content-type=multipart/form-data")
    public IMoocJSONResult upload(String userId, String bgmId, double videoSeconds, int videoWidth, int videoHeight, String desc,
                                  @ApiParam(value = "短視頻", required = true) MultipartFile file) throws Exception {

}

注意到消息頭headers = "content-type=multipart/form-data"，那麼前端傳過來的參數

formData:{
    userId: userInfo.id,
    bgmId: bgmId,
    desc: desc,
    videoSeconds: duration,
    videoWidth: tmpWidth,
    videoHeight: tmpHeight
  }

五、用對象來接收參數能夠在pojo上作配置

@ApiModel(value = "用戶對象",description = "這是用戶對象 ")
public class Users {
    @ApiModelProperty(hidden = true)
    private String id;

    @ApiModelProperty(value = "用戶名", name = "username",example = "imoocuser",required = true)
    private String username;

    @ApiModelProperty(value = "密碼", name = "password",example = "123456",required = true)
    private String password;

    @ApiModelProperty(hidden = true)
    private String faceImage;

    private String nickname;
    @ApiModelProperty(hidden = true)
    private Integer fansCounts;
    @ApiModelProperty(hidden = true)
    private Integer followCounts;
    @ApiModelProperty(hidden = true)
    private Integer receiveLikeCounts;
}

若是設置了hidden = true，那麼文檔裏面上傳的參數就不會顯示出來

六、測試接口