Swagger2的注解使用及基本配置

• Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

 作用：

    1. 接口的文档在线自动生成。

    2. 功能测试。

• 首先我们先对项目pom.xml进行配置：

    io.springfox
    springfox-swagger2
    2.7.0


    io.springfox
    springfox-swagger-ui
    2.7.0

• 然后我们添加一个配置类，其主要是对swagger的一些默认的配置进行修改，其实不加也是可以的：

/**
 * Swagger2的接口配置
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 创建API
     */
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.server.demo")) //指定包
                // .apis(RequestHandlerSelectors.any()) 扫描所有包
                .paths(PathSelectors.any())
                .build();
    }
    /**
     * 添加摘要信息
     * 用ApiInfoBuilder进行定制
     */
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("积分系统_接口文档")
                .description("用于积分开发组生成RestApi风格的接口")
                .contact(new Contact("名称", "地址", "邮箱"))
                .version("版本号")
                .build();
    }
}

• 对于具体的类与方法也要标注清楚，方便文档的阅读：

/**
 * 日常任务
 */
@RestController
@RequestMapping("/normal_task")
@Api(value="日常任务",description="日常任务相关信息接口")
public class NormalTaskControllor {
    
    @RequestMapping("/complete")
    @ResponseBody
    @ApiOperation(value="获取所有user",notes="获取所有user，无需参数", httpMethod = "POST")
    @ApiResponses({ @ApiResponse(code = Code.OK, message = "操作成功"),
            @ApiResponse(code =Code.FAIL , message = "服务器内部异常"),
            @ApiResponse(code =Code.SIGN_CHECK, message = "权限不足") })
    public OO add(@ApiParam(value = "用户id", required = true) @RequestParam("uid")  String uid){
        //return normalTaskService.userTaskComplete(uid);
        return null;
    }

}

• 如果请求的方法不指定用何种请求方式，最终界面会出现多个请求的类型供选择，不过还是要指定为好，不然太多眼花缭乱，而且基本上是不必要的，效果图如下：

当然，对接收参数的标识也可用@ApiImplicitParams({ @ApiImplicitParam(paramType = "query", dataType = "int", name = "uid", value = "信息id", required = true) })表示，如果接收是一个实体类然后返回实体的话，可以在实体类的每个属性上注解

@ApiParam(name = "imgUrl", value = "图片路径", required = true)和@ApiModelProperty(name="giftName",value="礼物名称",required=true)

到时UI上请求和返回的数据中都将有说明。

注解	说明
@Api()	用于类，表示标识这个类是swagger的资源
@ApiOperation()	用于方法，表示一个http请求的操作
@ApiParam()	用于方法，参数，字段说明，表示对参数的添加元数据（说明或是否必填等）
@ApiModel()	用于类，表示对类进行说明，用于参数用实体类接收
@ApiModelProperty()	用于方法，字段，表示对model属性的说明或者数据操作更改
@ApiIgnore()	用于类，方法，方法参数 ，表示这个方法或者类被忽略
@ApiImplicitParam()	用于方法 ，表示单独的请求参数
@ApiImplicitParams()	用于方法，包含多个 @ApiImplicitParam

 

对于只是想体验一下的童鞋来说，其实只需要将jar包引入，然后在springboot的启动类上将@EnableSwagger2注上，然后打开http://localhost:8080/swagger-ui.html即可看到啦~~