Swagger2详解

àì夳堔傛蜴生んèń 2022-04-15 01:54 260阅读 0赞

## 一、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 两个核心依赖 ###

<dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>${swagger.version}</version>
            </dependency>
    
            
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>${swagger.version}</version>
            </dependency>

###  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<SwaggerResource> get() {
            List<SwaggerResource> resources = new ArrayList<>();
            List<Route> 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;
        }
    
    }