Swagger2使用记录

注： 主要记录SpringBoot中使用Swagger2的步骤；

1. 引入依赖

引入maven依赖：

<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger2artifactId>
dependency>
<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger-uiartifactId>
dependency>

2. 编写配置类

@Configuration
@EnableSwagger2
public class SwaggerConfigurer {

    @Bean
    public TypeResolver typeResolver() {
        return new TypeResolver();
    }

    @Bean
    @Autowired
    public Docket createRestApi(TypeResolver typeResolver) {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.xxx.portal.controller")).paths(PathSelectors.any()).build();
    }

    // 添加应用、服务信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("Swagger2Test").contact(new Contact("Your name",
                "Your Service's url",
                "Your email")).version("2.0").build();
    }
}

注：

1. title：即Swagger页面上的标题（非标签标题），建议使用应用名字；
2. Contact("name", "url", "email")：表示相关信息；
3. version：表示当服务版本，根据自己应用的版本填写即可；
4. basePackage：表示Swagger需要扫描的包注解，一定要写对，否则打开Swagger页面将会为空【重要】；

3. 使用Swagger标签

 只记录几个常用标签：

1. @Api(tag=..., description=...)：主要打在Controller上面，tag是String[]，value是String，比如@Api(tags = "Activity", description = "活动相关")；
2. @ApiOperation：主要用于Controller中具体的方法上（准确点说应该是一个内部ttp请求的方法），用于说明这个RequestMapping的作用，比如@ApiOperation(name = "Activity Info", value = "获取活动基本信息")，这个注解中也有tag（会单独生成条Swagger记录，不推荐使用这个属性标签）；
3. @ApiImplicitParam：这个可以直接方法体上对传入参数进行注解说明，不要求注解在传入的参数上(相对于@ApiParam必须注解到对应的参数上更加灵活)，内部有几个属性：
   • name：参数名（一定要和参数对应上）；
   • value：参数含义说明；
   • paramType：参数类型，可取值为–"path"(url参数)、"query"(请求参数)、"body"(请求体参数)、"header"(头部参数)、"form"(表单参数)；
   • required：该参数是否必须，true/false；
   • dataType：参数类型，可选值有–string、number（包含整数和浮点数，即包含integer）、integer、boolean、array、object；
4. @ApiImplicitParams：和上述注解对应的，类型为ApiImplicitParam[]，用于对多个参数说明；

注：上述的@ApiImplicitParam注解中name属性一定要和传入的参数名一致，这里的参数名是指和HTTP方法直接相关的参数，而不是经过序列化的后的参数名，比如：

@ApiOperation(value = "获取活动相关的奖品列表")
@ApiImplicitParams({
        @ApiImplicitParam(name = "activity_id", value = "活动id", paramType = "path", required = true, dataType = "integer"),
        @ApiImplicitParam(name = "activity_name", value = "活动名字", paramType = "query", required = true, dataType = "string")
})
@RequestMapping(value = "/{activity_id}/awards", method = RequestMethod.GET)
public GeneralResponse<List<AwardBean>> getActivityAwards(@PathVariable("activity_id") Integer activityId, @RequestParam("activity_name") String name) {
    return new GeneralResponse<>(activityAwardService.listAward(activityId));
}

上述@ApiImplicitParam中的name属性应该直接填写URL中的activity_id和activity_name才能对应上，如果写成序列化后的参数名activityId和name就不能对应上，会直接生成额外Swagger两条的参数说明。

上述的标签基本可以满足需求了，但发现如果是传入的参数是一个对象的时候，想对对象中的一些属性做一些解释说明的时候，发现可以在Controller中不要管他，只要在对应的对象上进行如下注解即可，如：

@ApiModel
public class ContributorBean {
    /**
     * 姓名
     */
    @ApiModelProperty(name = "name", value = "贡献者姓名", required = true)
    private String name;
    /**
     * 文件id
      */
    @ApiModelProperty(name = "fileIds", value = "贡献文件的id", required = true)
    private List<Long> fileIds;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public List<Long> getFileIds() {
        return fileIds;
    }

    public void setFileIds(List<Long> fileIds) {
        this.fileIds = fileIds;
    }
}

然后再Controller中的方法体上直接使用@ApiImplicitParam注解指定上述类型的参数即可。

4. 启动查看

启动项目后，直接访问http://localhost:8090/portal/swagger-ui.html项目地址即可，平心而论，个人觉的代码耦合度太高，尤其是@ApiModel注解更是深入到了封装的对象中。

注：自己实现了WebMvcConfigurer接口后，不能去重写里面的configureMessageConverters方法，否则可能导致无法数据无法正常序列化从而Swagger不能正常显示；