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 {@Extension(
    properties = {@ExtensionProperty(
    name = "",
    value = ""
)}
)};

    boolean ignoreJsonView() default false;
}

例子：

 @ApiOperation(value = "登录检测", notes="根据用户名、密码判断该用户是否存在")
        public UserModel login(@RequestParam(value = "name", required = false) String account,

1.3 @ApiImplicitParam：

用在方法上，表示对参数的说明，@ApiImplicitParams为一组@ApiImplicitParam

public @interface ApiImplicitParam {

    //参数名
    String name() default "";

    //参数说明
    String value() default "";
    
    //默认值
    String defaultValue() default "";

    String allowableValues() default "";
    
    //是否必须
    boolean required() default false;

    String access() default "";

    boolean allowMultiple() default false;
    
    //参数类型，默认String，其它值dataType="Integer"
    String dataType() default "";
    
    //参数对象类型
    Class dataTypeClass() default Void.class;
    
    //参数来源：header(@RequestHeader),query(@RequestParam),path(@PathVariable)
    String paramType() default "";

    String example() default "";

    Example examples() default @Example({@ExampleProperty(
    mediaType = "",
    value = ""
)});

    String type() default "";

    String format() default "";

    boolean allowEmptyValue() default false;

    boolean readOnly() default false;

    String collectionFormat() default "";
}

例子：

	/**
	 * 获取文件信息
	 *
	 * @param bucketName
	 * @param fileKey
	 * @return
	 */
	@ApiOperation(value = "获取文件信息",response = ObjectListing.class)
	@ApiImplicitParams({
		@ApiImplicitParam(name = "bucketName", value = "存储空间名称"),
		@ApiImplicitParam(name = "fileKey", value = "文件key")})
	@GetMapping("/info")
	public Result findFile(String bucketName, String fileKey) {
}

1.4 @ApiModel

用于响应类上，表示一个返回响应数据的信息

public @interface ApiModel {
    
    //文字描述实体类
    String value() default "";

    String description() default "";
      
    //父类
    Class parent() default Void.class;

    String discriminator() default "";
    
    //子类
    Class[] subTypes() default {};

    String reference() default "";
}

例子：

@ApiModel(value="user对象",description="用户对象user")
public class User implements Serializable{

}

1.5 @ApiModelProperty

用在属性上，描述响应类的属性

public @interface ApiModelProperty {
    //文字说明属性
    String value() default "";

    //属性名，可以覆盖
    String name() default "";
    
    //允许的值
    String allowableValues() default "";

    String access() default "";
    
    //备注说明
    String notes() default "";
    
    //参数类型
    String dataType() default "";

    boolean required() default false;

    int position() default 0;

    boolean hidden() default false;

    String example() default "";

    /** @deprecated */
    @Deprecated
    boolean readOnly() default false;

    ApiModelProperty.AccessMode accessMode() default ApiModelProperty.AccessMode.AUTO;

    String reference() default "";
    
    //是否能为空
    boolean allowEmptyValue() default false;

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

    public static enum AccessMode {
        AUTO,
        READ_ONLY,
        READ_WRITE;

        private AccessMode() {
        }
    }
}

例子：  

  @ApiModelProperty(value="状态",name="state",required=true)
      private Integer state;

1.6 @ApiResponse：

用在请求的方法上，表示一组响应

public @interface ApiResponse {
    //结果码
    int code();
    //结果信息
    String message();
    //返回对象
    Class response() default Void.class;

    String reference() default "";

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

    String responseContainer() default "";

    Example examples() default @Example({@ExampleProperty(
    value = "",
    mediaType = ""
)});
}

例子：

 @ApiResponses({
            @ApiResponse(code=400,message="请求参数没填好"),
            @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
        })
        public JsonResult update(@PathVariable String id, UserModel model){}

1.7 @ApiParam

用在请求方法中，描述参数信息

public @interface ApiParam {
    
    //参数名
    String name() default "";
    //参数描述
    String value() default "";

    String defaultValue() default "";

    String allowableValues() default "";

    boolean required() default false;

    String access() default "";

    boolean allowMultiple() default false;

    boolean hidden() default false;

    String example() default "";

    Example examples() default @Example({@ExampleProperty(
    mediaType = "",
    value = ""
)});

    String type() default "";

    String format() default "";

    boolean allowEmptyValue() default false;

    boolean readOnly() default false;

    String collectionFormat() default "";
}

例子：

public Result findFile(@ApiParam(name = "buccketName",value = "存储空间") String bucketName, String fileKey) {}

二、SpringCloud整合 Swagger

2.1 两个核心依赖

        
        
            io.springfox
            springfox-swagger2
            ${swagger.version}
        

        
        
            io.springfox
            springfox-swagger-ui
            ${swagger.version}
        

 2.2 服务层注入swaggerConfig

@Configuration
@ConditionalOnProperty(value = "swagger.enabled", havingValue = "true", matchIfMissing = true)
@EnableSwagger2
public class SwaggerConfig {
    @Value("${swagger.base-package:}")
    private String basePackage;
    @Value("${swagger.title:}")
    private String title;
    @Value("${swagger.version:}")
    private String version;
    @Value("${spring.application.name}")
    private String appName;
    @Value("${spring.application.version:}")
    private String appVersion;

    @Bean
    public Docket createRestApi() {
        return (new Docket(DocumentationType.SWAGGER_2)).apiInfo(this.apiInfo()).select()
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                .paths(PathSelectors.any()).build();
    }
   
   
    private ApiInfo apiInfo() {
        if (StringUtils.isEmpty(title)) title = appName + " apis";
        if (StringUtils.isEmpty(version)) version = appVersion;
        return (new ApiInfoBuilder()).title(title).version(version).build();
    }
}

2.3 网关层实现swagger服务聚合

/**
 * @author sunyiran
 * @createTime 2019-08-16 15:53
 */
@Component
@Primary
public class SwaggerUIConfig implements SwaggerResourcesProvider {

    private final RouteLocator routeLocator;

    public SwaggerUIConfig(RouteLocator routeLocator) {
        this.routeLocator = routeLocator;
    }

    @Override
    public List get() {
        List resources = new ArrayList<>();
        List routes = routeLocator.getRoutes();
        for (Route route : routes) {
            if (!"api".equals(route.getId()) && !"consul".equals(route.getId()))
                // swagger的json相应内容请求路径：v2/api-docs
                resources.add(swaggerResource(route.getId(), route.getFullPath().replace("**", "v2/api-docs")));
        }
        return resources;
    }

    private SwaggerResource swaggerResource(String name, String location) {
        SwaggerResource swaggerResource = new SwaggerResource();
        swaggerResource.setName(name);
        swaggerResource.setLocation(location);
        swaggerResource.setSwaggerVersion("2.0");
        return swaggerResource;
    }

}