Swagger2详解

一、Swagger注解

1.1 @Api

用在请求的类上，表示对类的说明

public @interface Api {

    //说明接口，无实际作用
    String value() default "";

    //文字说明接口，显示在UI上
    String[] tags() default {""};

    /** @deprecated */
    @Deprecated
    String description() default "";

    /** @deprecated */
    @Deprecated
    String basePath() default "";

    /** @deprecated */
    @Deprecated
    int position() default 0;

    //允许返回类型
    String produces() default "";

    //允许接收类型
    String consumes() default "";

    //允许的协议：http, https, ws, wss
    String protocols() default "";

    //所需访问权限
    Authorization[] authorizations() default {@Authorization("")};

    boolean hidden() default false;
}

例子：

/**
 * 存储空间操作（基于远程操作，不考虑事务）
 *
 * @author sunyiran
 * @date 2018-11-15
 */
@Api(tags = "存储空间管理")
@RestController
@RequestMapping("/bucket")
public class BucketController {
}

1.2 @ApiOperation

用于方法；表示一个http请求的操作 

public @interface ApiOperation {

    //方法文字说明
    String value();

    //备注提示
    String notes() default "";

    String[] tags() default {""};

    //返回对象类型
    Class<?> response() default Void.class;

    //声明包装的响应容器（返回对象类型）:"List", "Set","Map"
    String responseContainer() default "";

    // responseReference  指定对响应类型的引用。将覆盖任何指定的response（）类
    String responseReference() default "";
    
    //restful风格
    String httpMethod() default "";

    /** @deprecated */
    @Deprecated
    int position() default 0;
    
    //别名
    String nickname() default "";

    String produces() default "";

    String consumes() default "";

    String protocols() default "";

    Authorization[] authorizations() default {@Authorization("")};

    boolean hidden() default false;

    ResponseHeader[] responseHeaders() default {@ResponseHeader(
    name = "",
    response = Void.class
)};

    int code() default 200;

    Extension[] extensions() default {@Extensi