• 常用Swagger注解汇总
• 控制器层
  • @Api
  • @ApiOperation
  • @ApiImplicitParam
  • @ApiImplicitParams
  • @ApiParam
• 实体层
  • @ApiModel
  • @ApiModelProperty

@Api

此注解应用于类、接口或者枚举上，启动应用时被标注的类会扫描到 swagger 源中。默认情况下，swagger 核心仅扫描带有 @Api 注解的类而无视其他的源数据 (例如：JAX-RS 端口、Serlvet 等等)

不能标注在方法上且一般不单独使用，常见的做法是搭配 @ApiOperation 注解，作为业务接口类的说明。

//
// Source code recreated from a .class file by IntelliJ IDEA
// (powered by FernFlower decompiler)
//

package io.swagger.annotations;

import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Inherited
public @interface Api {
    String value() default "";

    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 "";

    String protocols() default "";

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

    boolean hidden() default false;
}

从源码我们可以看到 @Api 注解除了已废弃的3个，共有 7 个属性，不过这里面只有下面这1个属性比较常用：

1. tags (接口业务所属分组)

属性	数据类型	默认值	作用	示例	说明
value	String	“”	接口分组说明，在实际开发中并不常用，且值会被 tags 属性覆盖	@Api(value = “操作名称”) 或 @Api(“操作名称”)	隐式地设置操作标签 (即操作名称)，旧版本支持 (阅读描述)。 在 Swagger 核心 1.3.X 的版本中，此属性仅作为主机 API 资源的声明路径，到 1.5.X 版本之后就不再关联了。
hidden	boolean	false	隐藏该分组下的所有接口。此外要注意的是，接口的显示隐藏应该根据特定的安全策略和特定客户需求来确定	@Api(hidden = true)	隐藏资源下的操作。 此属性的值默认为 false，当设置为 true 时，该分组的所有操作都会在 swagger 文档中被隐藏，适用于接口暂时不需要使用时的情况。
produces	String	“”	指定的content-type 的输出	@Api(produces=“application/json”	此属性在新版本的 swagger 中已不再使用，仅用于向下兼容旧版本。对应此资源下操作生成的字段。 获取逗号分割的内容类型值，例如，“application/json”，“application/xml” 将会提醒操作生成 JSON 或 XML 输出。 对于 JAX-RS 资源，如果存在将会自动获取 @Produces 注解的值，同时也可用于覆盖 Swapper 文档的 @Produces 的值。
consumes	String	“”	指定的content-type 的输入	@Api(consumes=“application/xml”)	对应此资源下操作消费的字段。 获取逗号分割的内容类型值。例如例如，“application/json”，“application/xml” 将会提醒操作接收 JSON 或 XML 输入。 对于 JAX-RS 资源，如果存在将会自动获取 @Consumes 注解的值，同时也可用于覆盖 Swagger 文档的 @Consumes 的值。
protocols	String	“”	网络请求协议	@Api(protocols = “http,https”)	设置此资源下操作的指定协议(或方案)。 以逗号分割可用的协议值，可用值：http, https, ws, wss
authorizations	Authorization[]	@Authorization(value = “”)	规定接口分组的授权方案		对应操作对象的安全字段。 获取此资源下操作的授权 (安全需求) 列表，这可能会被特定的操作覆盖。

@ApiOperation

@ApiOperation 注解可应用于方法或类上，通常标注在方法上作为业务接口的名称，描述其操作或者描述针对于特定路径的 HTTP 方法。默认情况下，具有相同效果的操作被分组在一个单独的操作对象中，而 HTTP 方法和路径的组合将会创建一个独一无二的操作。此外，此注解提供了丰富的属性来允许我们自定义接口的描述信息，包括接口名称和所属分组等。

package io.swagger.annotations;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiOperation {

    String value();

    String notes() default "";

    String[] tags() default "";

    Class<?> response() default Void.class;

    String responseContainer() default "";

    String responseReference() default "";

    String httpMethod() default "";

    @Deprecated int position() default 0;

    String nickname() default "";

    String produces() default "";

    String consumes() default "";

    String protocols() default "";

    Authorization[] authorizations() default @Authorization(value = "");

    boolean hidden() default false;

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

    int code() default 200;

    Extension[] extensions() default @Extension(properties = @ExtensionProperty(name = "", value = ""));

    boolean ignoreJsonView() default false;
}