SpringBoot五：整合swagger文檔工具

在開發中，我們需要測試或者提供給別人文檔，測試的話我們一般需要使用postman等測試工具，文檔提供只是內部人員使用，專門寫一個word文檔有點麻煩，而且每次修改的時候都需要發一個新的文檔。

swagger就可以很好地解決上面的文檔，它可以提供一個線上文檔地址，每次修改後只要發佈，文檔就會更新。

首先添加需要的依賴

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>

 配置類：如果只是簡單的使用我們類內部可以是空的，這個時候訪問地址http://localhost:8088/swagger-ui.html頁面如下

@Profile({"dev", "test")//設置什麼環境提供文檔，一般只開發環境(dev)，測試環境(test)需要，正式環境(prod)關閉
@Configuration
@EnableSwagger2
public class SwaggerConfig {

}

上面沒有任何的描述，我們需要加一點信息，讓使用的人更清楚。

@Profile({"dev"})//設置什麼環境提供文檔，一般只開發環境(dev)，測試環境(test)需要，正式環境(prod)關閉
@Configuration
@EnableSwagger2
public class SwagerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.demo.controller"))//掃描的包路徑
                .paths(PathSelectors.any())//設置哪些請求加入文檔
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot整合swagger在線文檔")//標題
                .description("測試用例")//說明
                .contact(new Contact("fusheng","www.baidu.com",""))//文檔聯繫信息
                .version("1.0")//版本號
                .build();
    }
}

@RestController
@Api(value = "學校比賽controller", description = "學校信息操作")
public class MatchController {
    @Autowired
    CollegeService service;

    @GetMapping(value = "/college")
    @ApiOperation(value = "通過名字獲取學校")
    public BaseResult<CollegeDto> getCollegeByName(@RequestParam(name = "name") String name) {
        CollegeDto college = service.findCollegeByName(name);
        return BaseResult.success(college);
    }

    @GetMapping(value = "/college2")
    @ApiOperation(value = "通過id獲取學校")
    public BaseResult<CollegeDto> getCollegeById(@ApiParam(name = "id", value = "學校id", required = true) String id) {
        CollegeDto college = service.findCollegeById(id);
        return BaseResult.success(college);
    }

    @PostMapping(value = "/college/save")
    @ApiOperation("新建學校信息")
    public BaseResult<String> saveCollege(@RequestBody @Valid CollegeReq req) {
        service.saveCollege(req);
        return BaseResult.success("success");
    }

    @GetMapping("/college3")
    @ApiOperation("通過名字和地址查詢學校")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "學校名稱", paramType = "query", required = true),
            @ApiImplicitParam(name = "address", value = "地址", paramType = "query")
    })
    public BaseResult<CollegeDto> getCollege(String name, String address) {
        CollegeDto college = service.findByNameAndTime(name, address);
        return BaseResult.success(college);
    }

    @GetMapping("/college/team")
    @ApiOperation("通過名字查詢學校及其隊伍信息")
    public BaseResult<CollegeTeamDto> getCollegeTeam(@RequestParam(name = "name") String name) {
        CollegeTeamDto dto = service.findCollegeTeam(name);
        return BaseResult.success(dto);
    }

}

@Api:用在類上，對類做一個說明。

@ApiOperation：用於方法，解釋這個方法的作用。

@ApiParam：可以用於參數或者方法上，用於參數上類似@RequestParam，不過name表示請求的參數，value是說明，required默認是false，和@RequestParam不一致，在項目中兩個最好不要混用。@ApiParam用於方法上時，雖然不報錯，沒有起到應有的作用 （待考究）。

@ApiImplicitParams用於多個參數時。

@ApiImplicitParam，單個參數，paramType必填，類型有

             header --> ：@RequestHeader
             query -->：@RequestParam
             path-->@PathVariable
             body -->  @RequestBody User user
             form（不常用）  

@Data
@ApiModel(description = "學校信息")
public class CollegeReq {
    @NotNull
    @ApiModelProperty(value = "學校名稱",required = true)
    private String name;

    @NotNull
    @ApiModelProperty(value = "學校地址",required = true)
    private String address;

    @ApiModelProperty("學校聯繫方式")
    private String phone;

    @ApiModelProperty("學校官網")
    private String web;

    @AllowValue(allowValues = {"0","1"})
    @ApiModelProperty(hidden = true)
    private String type;
}

@ApiModel：用於類，對實體類進行說明。

@ApiModelProperty：用於字段，對字段進行說明，hidden=true在生成swagger文檔是會不顯示這個字段。