云服务器内容精选

  • 4、x-annotations 作用: 添加指定的注解。 该标签用于在api的参数或者dto指定属性上添加注解。 标签值类型: List 使用位置: paths.path.operation.parameters.x-annotations(定义在api中的参数上时,只在此参数上生成对应的注解) definitions.model.properties.property.x-annotations(定义在dto的字段上时,只在此字段上生成对应的注解) 使用示例: Card: type: "object" properties: id: type: "string" description: "id" example: "id" balance: type: "integer" format: "int64" description: "balance" example: 123 address: type: "string" description: "address" example: "address" x-annotations: - "@InjectMocks" # 此处在address属性上添加了一个 @InjectMocks 注解 x-imports: - "org.mockito.InjectMocks;" # x-annotations实际是把 @InjectMocks当做字符串添加到了address上,所以需要自己通过x-imports导入相应的类 creator: type: "string" description: "creator" example: "creator" create_time: type: "string" format: "date-time" default: "CURRENT_TIMESTAMP" description: "create time" example: "2020-02-27 15:00:08" modify_time: type: "string" format: "date-time" default: "CURRENT_TIMESTAMP" description: "modified time" example: "2020-02-27 15:00:08" description: type: "string" description: "description info" example: "description" xml: name: "card" namespace: "com.huaweicloud.icsl.model" 使用效果: 使用前: public class Card implements Serializable { private static final long serialVersionUID = 1L; ----- @JsonProperty("address") private String address = null; ---- } 使用后: public class Card implements Serializable { private static final long serialVersionUID = 1L; ------- @JsonProperty("address") @InjectMocks // 通过 x-annotations 引入的注解 private String address = null; -------- }
  • 21、x-pom-gav 作用 自定义标签-pom坐标引入。 标签值类型 List 使用位置 x-pom-gav components.schemas.model.x-pom-gav components.schemas.model.properties.property.x-pom-gav paths.path.operation.x-pom-gav paths.path.operation.parameters.name.x-pom-gav x-pom-gav在Swagger文件中的位置可以是类级别、方法级别、参数级别,groupId、artifactId、version按照顺序用:连接,全局有一个地方定义即可,不需要重复定义。 使用示例 swagger: "2.0" info: description: "" version: "v1" title: "testSwagger" termsOfService: "http://www.coarl.org/service.html" host: "git.huawei.com" basePath: "/testswagger" x-entity-package: "customdto" x-interface-name-style: SERVICE_IMPL_AND_NO_I_INTERFACE_PREFIX x-user-defined-consumes: true x-pom-gav: # 手动引入hibernate-validator:依赖 - "org.hibernate.validator:hibernate-validator:8.0.1.Final" ------- 使用效果: 使用前: pom中没有org.hibernate.validator:hibernate-validator:8.0.1.Final的依赖 使用后: pom中生成org.hibernate.validator:hibernate-validator:8.0.1.Final的依赖
  • 18、x-interface-name-style 作用: 控制自定义接口、实现类命名风格。 标签值类型: enum(DEFAULT,SERVICE_IMPL_AND_NO_I_INTERFACE_PREFIX),配置为DEFAULT时和不配置此参数效果相同。 使用位置: x-interface-name-style 使用示例: swagger: "2.0" info: description: "" version: "v1" title: "testSwagger" termsOfService: "http://www.coarl.org/service.html" host: "git.huawei.com" basePath: "/testswagger" x-entity-package: "customdto" x-interface-name-style: SERVICE_IMPL_AND_NO_I_INTERFACE_PREFIX ------------ 使用效果: 使用前: service类的命名为 I+tag驼峰+ service eg: IOrderService 使用后: service类的命名为 tag驼峰+ service eg: OrderService
  • 5、x-class-annotations 作用: 添加指定的注解。 该标签用于在api接口或者dto类上添加指定的注解。 标签值类型: List 使用位置: x-class-annotations(定义在swagger的最外层时,会在所有的api接口上都添加指定的注解) components.schemas.model.x-class-annotations(定义dto对象上时,只在该对象上添加指定的注解) 使用示例: swagger: "2.0" info: description: "" version: "v1" title: "testSwagger" termsOfService: "http://www.coarl.org/service.html" host: "git.huawei.com" basePath: "/testswagger" x-imports: - "org.springframework.stereotype.Controller;" # 使用的时候结尾一定要带上 ; - "org.springframework.transaction.annotation.Transactional;" x-class-annotations: #此处添加的注解,在所有生成的api上都会添加 - "@Controller" # 此处会将 @Controller识别为一个字符串添加到api接口类上,并不会导入相应的包,需要使用 x-imports标签手动导入相应的包 - "@Transactional" # 此处会将 @Transactional识别为一个字符串添加到api接口类上,并不会导入相应的包,需要使用 x-imports标签手动导入相应的包 使用效果: 使用前: package com.huaweicloud.icsl.api; import ------ /** * CARDApi interface */ public interface CARDApi { ----------- } 使用后: package com.huaweicloud.icsl.api; import org.springframework.stereotype.Controller; // 通过x-imports 引入的导包 import org.springframework.transaction.annotation.Transactional; // 通过x-imports 引入的导包 /** * CARDApi interface */ @Controller // 通过x-class-annotations 引入的注解 @Transactional // 通过x-class-annotations 引入的注解 public interface CARDApi { ----------- }
  • 6、x-controller-annotations 作用: 添加指定的注解。 该标签用于在api实现类上添加指定的注解。 标签值类型: String 使用位置: x-class-annotations(定义在swagger最外层,所有的api实现类上都会添加指定注解) components.schemas.model.x-class-annotations(定义在指定tag下,只会在具体api实现类上添加指定注解) 使用示例: swagger: "2.0" info: description: "" version: "v1" title: "testSwagger" termsOfService: "http://www.coarl.org/service.html" host: "git.huawei.com" basePath: "/testswagger" x-imports: - "org.springframework.context.annotation.Profile;" # 使用的时候结尾一定要带上 ; x-controller-annotations: # 此处添加的注解,在所有生成的api实现类上都会添加,需要使用x-imports手动导入相应的包 - '@Profile("test")' 使用效果: 使用前: public class CardApiController implements CardApi { ------ } 使用后: @Profile("test") // 通过x-controller-annotations引入的注解 public class CardApiController implements CardApi { ------ }
  • 9、x-type 作用: 给dto的字段设置指定的类型。 标签值类型: String 使用位置: components.schemas.model.prorperties.field.x-type(设置在dto的指定字段上时,改变该字段的类型为指定类型) 使用示例: definitions: Contain: type: "object" x-generic: T x-extends: Parent properties: name: type: "string" description: "" example: data: type: "string" x-type: T # 通过x-type指定data的类型为T, 此处是将T当为一个字符串设置上,如果设置为一个对象时,需要使用x-imports手动导入相应的包 xml: name: "Contain" namespace: "com.huaweicloud.icsl.app.dto" --------------- 使用效果: 使用前: public class Contain implements Serializable { private static final long serialVersionUID = 1L; @JsonProperty("name") private String name = null; @JsonProperty("data") private String data = null; } 使用后: public class Contain implements Serializable { private static final long serialVersionUID = 1L; @JsonProperty("name") private String name = null; @JsonProperty("data") private T data = null; }
  • 16、x-enum-class-name 作用 用于标识查询参数对应的枚举类。 标签值类型 String 使用位置 paths.path.operation.parameters.fields.x-enum-value-type 对应的是swagger中已定义的枚举对象名字。 使用示例 Paths: /v1/orders/{order_id}/order-details: get: tags: - "Order" summary: "查询OrderDetail" description: "Returns OrderDetail" operationId: "ListOrderDetails" x-is-registered: 'N' x-support-sdk: 'N' x-mybatis-paging: true consumes: - "application/json" produces: - "application/json" parameters: - name: "status" in: "query" description: "status" required: false type: "string" x-enum-class-name: "OrderStatus" #此标签只在查询参数中使用 -------- 使用效果: 使用前: public class ListOrderDetailsQo implements Serializable { private static final long serialVersionUID = 1L; @JsonProperty("status") private Object status = null; ------------------- } 使用后: public class ListOrderDetailsQo implements Serializable { private static final long serialVersionUID = 1L; @JsonProperty("status") private OrderStatus status = null; ------------------- }
  • 17、x-entity-package 作用: 用于在swagger中指定实体类dto生成的包名。 标签值类型: String 使用位置: x-entity-package(定义在swagger的最外层) 使用示例: swagger: "2.0" info: description: "" version: "v1" title: "testSwagger" termsOfService: "http://www.coarl.org/service.html" host: "git.huawei.com" basePath: "/testswagger" x-entity-package: "customdto" ------------ 使用效果: 使用前: #dto对象生成目录 xxx.xx.xx.dto 使用后: #dto对象生成目录 xxx.xx.xx.customdto
  • 2、x-default-empty 作用: 只支持get请求,指定String类型参数生成默认值为""。 需要配合metadata元数据中generatorPolicy的queryParamLimit使用,当将请求参数转换为对象后此标签才会生效。 标签值类型: boolean 使用位置: paths.path.operation.parameters.name.x-default-empty 当该标签置为true时,原定义默认值的default标签失效,该标签只可用于定义String参数为""。 使用示例: paths: /v1/cards: get: # 该接口设置了查询参数转换为对象的功能,最终所有的参数都会自动定义到一个对象中 tags: - "CARD" summary: "查询所有Card" description: "Returns all Card" operationId: "ListCards" x-is-registered: 'N' x-support-sdk: 'N' x-mybatis-paging: true x-query-param-body: CardQo parameters: - name: "creator" in: "query" description: "creator" required: false type: "string" x-default-empty: true # 使用 x-default-empty 指定creator的默认值为 "" ----- 使用效果: 使用前: public class ListCardsQo implements Serializable { private static final long serialVersionUID = 1L; @JsonProperty("creator") private String creator = null; // 此处生成的creator默认值为 null ------ } 使用后: public class CardQo implements Serializable { // 该示例使用了x-query-param-body指定了对象名为CardQo,所以和使用前的的示例中类名不一样 private static final long serialVersionUID = 1L; @JsonProperty("creator") private String creator = ""; //此处生成的creator的默认值为 "" ------- }
  • 3、x-imports 作用: 自主定义类中需要添加的 import 引用。 标签值类型: List 使用位置: x-imports(当定义在swagger的最外层时,所有的类中都会引入import) components.schemas.model.properties.property.x-imports(当定义在dto的字段中时,只会在该dto类中引入import) definitions.model.x-imports(当定义在dto上时,只会在该dto类中引入import) paths.path.operation.x-imports(当定义在api中时,只会在该api中引入import) 在生成代码的时候,最终会有格式化的一个步骤,类上的无用import会被消除。 使用示例: swagger: "2.0" info: description: "" version: "v1" title: "testSwagger" termsOfService: "http://www.coarl.org/service.html" host: "git.huawei.com" basePath: "/testswagger" x-imports: - "org.springframework.stereotype.Controller;" # 使用的时候结尾一定要带上 ; - "org.springframework.transaction.annotation.Transactional;" 使用效果: 使用前:api类中不生成org.springframework.stereotype.Controller; 和org.springframework.transaction.annotation.Transactional;引用。 使用后:api类中生成如下引用。 import org.springframework.stereotype.Controller; # 通过x-import引入 import org.springframework.transaction.annotation.Transactional; # 通过x-import引入 public interface CARDApi { ------- );