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文档是会不显示这个字段。