# swagger标签使用指南
本章节为您介绍swagger的通用标签，帮助能更好的编辑swagger文件，完成业务设计。
#### 1、x-query-param-body
**作用：**
图1使用背景   
![](https://support.huaweicloud.com/usermanual-astropro/zh-cn_image_0000002016514353.png)
此功能需要结合metadata.json使用，对应到metadata.json中的参数：generatorPolicy.queryParamLimit
通过x-query-param-body标签，可以自定义转换的对象的名称。
**标签值类型** **：**
String
**使用位置** **：**
paths.path.operation.**x-query-param-body**（定义在指定Get请求的api上时，只影响该api）
**使用示例**：
```
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  #此处设置了x-query-param-body
      parameters:
        ------
```
**使用效果：**
使用前：
```
ResponseEntity<Message<PageInfo<Card>>> listCards( @RequestObject ListCardsQo listCardsQo);
```
使用后：
```
ResponseEntity<Message<PageInfo<Card>>> listCards( @RequestObject CardQo cardQo);
```
#### 2、x-default-empty
**作用** **：**
只支持get请求，指定String类型参数生成默认值为""。
![](https://support.huaweicloud.com/usermanual-astropro/public_sys-resources/note_3.0-zh-cn.png)
需要配合metadata元数据中generatorPolicy的queryParamLimit使用，当将请求参数转换为对象后此标签才会生效。
**标签值类型** **：**
boolean
**使用位置** **：**
paths.path.operation.parameters.name.**x-default-empty**
![](https://support.huaweicloud.com/usermanual-astropro/public_sys-resources/note_3.0-zh-cn.png)
当该标签置为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）
![](https://support.huaweicloud.com/usermanual-astropro/public_sys-resources/note_3.0-zh-cn.png)
在生成代码的时候，最终会有格式化的一个步骤，类上的无用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 {
   -------
);
```
#### 4、x-annotations
**作用** **：**
添加指定的注解。
![](https://support.huaweicloud.com/usermanual-astropro/public_sys-resources/note_3.0-zh-cn.png)
该标签用于在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;
    --------
}
```
#### 5、x-class-annotations
**作用** **：**
添加指定的注解。
![](https://support.huaweicloud.com/usermanual-astropro/public_sys-resources/note_3.0-zh-cn.png)
该标签用于在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
**作用** **：**
添加指定的注解。
![](https://support.huaweicloud.com/usermanual-astropro/public_sys-resources/note_3.0-zh-cn.png)
该标签用于在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 {
     ------
}
```
#### 7、x-method-annotations
**作用** **：**
添加指定的注解。
![](https://support.huaweicloud.com/usermanual-astropro/public_sys-resources/note_3.0-zh-cn.png)
该标签用于在api接口类中指定的api方法上添加注解。
**标签值类型** **：**
List
**使用位置** **：**
paths.path.operation.**x-method-annotations**（定义在指定api上，只在该api上添加相应注解）
**使用示例** **：**
```
paths:
  /v1/cards/{card_id}:
    get:
      tags:
      - "CARD"
      summary: "通过Card的id查询Card"
      description: "Returns a single Card"
      operationId: "ShowCardById"
      x-is-registered: 'N'
      x-support-sdk: 'N'
      x-method-source: metadata
      x-method-annotations:
        - "@C" # 此处会将 @C识别为一个字符串添加到方法上，并不会导入相应的包，需要使用 x-imports标签手动导入相应的包
      x-imports:
        - "org.checkerframework.checker.units.qual.C;"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "card_id"
        in: "path"
        description: "card_id"
        required: true
        type: "string"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Card"
        404:
          description: "Card not found"
```
**使用效果：**
使用前：
```
ResponseEntity<Message<Card>> showCardById( @PathVariable("card_id") String cardId);
```
使用后：
```
@C  // 通过 x-method-annotations 引入的注解
ResponseEntity<Message<Card>> showCardById( @PathVariable("card_id") String cardId);
```
#### 8、x-response-void
**作用** **：**
设置api接口返回值为void。
**标签值类型** **：**
Boolean
**使用位置** **：**
paths.path.operation.**x-response-void**（定义在指定api上时，只会将该api的返回值设置为void）
![](https://support.huaweicloud.com/usermanual-astropro/public_sys-resources/note_3.0-zh-cn.png)
当设置此值为true时，默认接口返回值为void，不再通过ResponseEntity包裹返回，默认值为false。
**使用示例** **：**
```
paths:
  /v1/orders/{order_id}/order-details/{order_detail_id}:
    get:
      tags:
      - "Order"
      summary: "通过OrderDetail的id查询OrderDetail"
      description: "Returns a single OrderDetail"
      operationId: "ShowOrderDetailById"
      x-is-registered: 'N'
      x-support-sdk: 'N'
      x-response-void: true  # 此处指定了该接口的返回值为void，使用了此标签后，设置的responses将不会生效
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "order_id"
        in: "path"
        description: "order_id"
        required: true
        type: "string"
      - name: "order_detail_id"
        in: "path"
        description: "order_detail_id"
        required: true
        type: "string"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/OrderDetail"
        404:
          description: "OrderDetail not found"
```
**使用效果：**
使用前：
```
ResponseEntity<Message<OrderDetail>> showOrderDetailById(@PathVariable("order_id") String orderId, @PathVariable("order_detail_id") String orderDetailId);
```
使用后：
```
void showOrderDetailById(@PathVariable("order_id") String orderId,  @PathVariable("order_detail_id") String orderDetailId)
```
#### 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;
}
```
#### 10、x-generic
**作用** **：**
为dto对象设置泛型。
![](https://support.huaweicloud.com/usermanual-astropro/public_sys-resources/note_3.0-zh-cn.png)
一个对象仅能支持一个泛型参数。
**标签值类型** **：**
String
**使用位置** **：**
definitions.model.**x-generic** （在dto对象上设置后，只对该dto对象产生影响）
**使用示例** **：**
```
Contain:
    type: "object"
    x-generic: T  # 此处通过x-generic为Contain对象设置泛型
    x-extends: Parent
    properties:
      name:
        type: "string"
        description: ""
        example: 
      data:
        type: "string"
        x-type: T  # 此处通过x-type为data字段设置为 T 泛型
    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<T> implements Serializable {
    private static final long serialVersionUID = 1L;
    @JsonProperty("name")
    private String name = null;
    @JsonProperty("data")
    private T data = null;
}
```
#### 11、x-extends
**作用** **：**
为dto对象定义继承对象。
**标签值类型** **：**
String
**使用位置** **：**
definitions.model.**x-extends** （定义在dto对象上时，只为该对象添加继承）
**使用示例** **：**
```
Contain:
    type: "object"
    x-generic: T
    x-extends: Parent  # 此处使用 x-extends标签让Contain继承Parent，Parent和Contain对象定义在同一个类中，当引入的是一个三方类的时候需要使用x-imports手动导包
    properties:
      name:
        type: "string"
        description: ""
        example: 
      data:
        type: "string"
        x-type: T
    xml:
      name: "Contain"
      namespace: "com.huaweicloud.icsl.app.dto"
```
**使用效果：**
使用前：
```
public class Contain<T> implements Serializable {
    private static final long serialVersionUID = 1L;
    @JsonProperty("name")
    private String name = null;
    @JsonProperty("data")
    private T data = null;
}
```
使用后：
```
public class Contain<T> extends Parent implements Serializable {
    private static final long serialVersionUID = 1L;
    @JsonProperty("name")
    private String name = null;
    @JsonProperty("data")
    private T data = null;
}
```
#### 12、x-returnType
**作用** **：**
定义方法的返回值类型。
**标签值类型** **：**
String
**使用位置** **：**
paths.path.operation.**x-returnType** （定义在指定api上时，只影响该api的返回值）
**使用示例** **：**
```
paths:
  /v1/cards/{card_id}:
    delete:
      tags:
      - "CARD"
      summary: "通过Card的id删除Card"
      description: "Delete a single Card"
      operationId: "DeleteCardById"
      x-is-registered: 'N'
      x-support-sdk: 'N'
      x-method-source: metadata
      x-returnType: Contain<Card>  # 此处使用x-returnType指定了方法的返回值为Contain<Card>
      x-imports:
        - "com.huaweicloud.icsl.app.customdto.Contain;" # 返回值引入了一个三方对象，需要使用 x-imports标签手动导入包
      parameters:
      - name: "card_id"
        in: "path"
        description: "card_id"
        required: true
        type: "string"
      responses:
        200:
          description: "successful operation"
          schema:
            type: "integer"
            format: "int32"
        404:
          description: "Card not found"
```
**使用效果：**
使用前：
```
ResponseEntity<Message<Integer>> deleteCardById(@PathVariable("card_id") String cardId);
```
使用后：
```
ResponseEntity<Message<Contain<Card>>> deleteCardById(@PathVariable("card_id") String cardId);
```
#### 13、x-exception
**作用** **：**
自定义api抛出的异常类。
**标签值类型** **：**
String
**使用位置** **：**
**x-exception**（定义在swagger的最外层，使用此标签后，所有的api中都会抛出此异常）
![](https://support.huaweicloud.com/usermanual-astropro/public_sys-resources/note_3.0-zh-cn.png)
该标签通常要配置x-imports一起使用。
**使用示例** **：**
```
swagger: "2.0"
info:
  description: ""
  version: "v1"
  title: "testSwagger"
  termsOfService: "http://www.coarl.org/service.html"
host: "git.huawei.com"
basePath: "/testswagger"
x-exception: "org.springframework.validation.BindException" #所有的api中都会抛出该异常
x-imports: 
  - "org.springframework.validation.BindException;"
```
**使用效果：**
使用前：
```
ResponseEntity<Message<Card>> addCard(@Valid @RequestBody Card body);
```
使用后：
```
ResponseEntity<Message<Card>> addCard( @RequestBody Card body) throws BindException;
```
#### 14、x-keep-original-tagname
**作用**
是否保持swagger中tag的原名称。
![](https://support.huaweicloud.com/usermanual-astropro/public_sys-resources/note_3.0-zh-cn.png)
AstroPro生成代码的时候，接口所在类的名称采用tag的驼峰格式+相应的后缀，当用户不想将tag转换为驼峰时可以使用此标签。
**标签值类型**
boolean
**使用位置**
**x-keep-original-tagname** （在swagger最外层使用）
![](https://support.huaweicloud.com/usermanual-astropro/public_sys-resources/note_3.0-zh-cn.png)
swagger中用户定义的tag名存在专有名词需要全大写；AstroPro默认会将全大写的转为驼峰。
**使用示例**
```
swagger: "2.0"
info:
  description: ""
  version: "v1"
  title: "testSwagger"
  termsOfService: "http://www.coarl.org/service.html"
host: "git.huawei.com"
basePath: "/testswagger"
x-keep-original-tagname: true
  /v1/cards:
    post:
      tags:
      - "CARD"  # 此处指定了  /v1/cards接口生成在 CARDxxxx的接口类中
      --------
```
**使用效果：**
使用前：
```
public interface CardApi {
    ResponseEntity<Message<Card>> addCard(@RequestBody Card body);
}
```
使用后：
```
public interface CARDApi {
    ResponseEntity<Message<Card>> addCard(@RequestBody Card body);
}
```
#### 15、x-enum-value-type
**作用**
用于标识定义的枚举的value的数据类型。
**标签值类型**
String
**使用位置**
definitions.model.**x-enum-value-type** （定义在指定枚举对象上时，只对该枚举对象产生影响）
![](https://support.huaweicloud.com/usermanual-astropro/public_sys-resources/note_3.0-zh-cn.png)
可选值有"STRING", "LONG", "INTEGER", "FLOAT", "DOUBLE", "BOOLEAN"，默认为"STRING"。
**使用示例**
```
definitions:
  Code:
    type: "string"
    enum: &Code
      - STARTING("1")
      - SELECTING("2")
      - PAYING("3")
      - PAYED("4")
    x-enum-value-type: "LONG"
    xml:
      name: "Code"
      namespace: ""
```
**使用效果：**
使用前：
```
public enum Code implements IEnum<String> {
    ----
    PAYED("4");
    Code(String value) {
        this.value = value;
    }
    private final String value;  # 此处类型为String
    @JsonValue
    public String getValue() {
        return value;
    }
    @JsonCreator
    public static Code fromValue(String value) {
        for (Code b : Code.values()) {
            if (String.valueOf(b.value).equals(value)) {
                return b;
            }
        }
        return null;
    }
}
```
使用后：
```
public enum Code implements IEnum<String> {
    ----
    PAYED("4");
    Code(String value) {
        this.value = value;
    }
    private final Long value;  # 此处类型为Long
    @JsonValue
    public String getValue() {
        return value;
    }
    @JsonCreator
    public static Code fromValue(String value) {
        for (Code b : Code.values()) {
            if (String.valueOf(b.value).equals(value)) {
                return b;
            }
        }
        return null;
    }
}
```
#### 16、x-enum-class-name
**作用**
用于标识查询参数对应的枚举类。
**标签值类型**
String
**使用位置**
paths.path.operation.parameters.fields.**x-enum-value-type**
![](https://support.huaweicloud.com/usermanual-astropro/public_sys-resources/note_3.0-zh-cn.png)
对应的是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
```
#### 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
```
#### 19、x-user-defined-produces
**作用** **：**
按照用户定义的produces生成代码。
**标签值类型** **：**
Boolean
**使用位置** **：**
**x-user-defined-produces**（定义在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"
x-interface-name-style: SERVICE_IMPL_AND_NO_I_INTERFACE_PREFIX
x-user-defined-produces: true
    ----
paths：
  /v1/cards/{card_id}:
    delete:
      tags:
      - "CARD"
      summary: "通过Card的id删除Card"
      description: "Delete a single Card"
      operationId: "DeleteCardById"
      x-is-registered: 'N'
      x-support-sdk: 'N'
      x-method-source: metadata
      x-returnType: Contain<Card>
      # 未在接口中定义produces标签
      -------
```
**使用效果：**
使用前：
```
@RequestMapping(value = "/v1/cards/{card_id}", produces = {"*/*"}, method = RequestMethod.DELETE)
    ResponseEntity<Message<Integer>> deleteCardById( @PathVariable("card_id") String cardId);
```
使用后：
```
@RequestMapping(value = "/v1/cards/{card_id}", method = RequestMethod.DELETE)
    ResponseEntity<Message<Contain<Card>>> deleteCardById(@PathVariable("card_id") String cardId);
```
#### 20、x-user-defined-consumes
**作用** **：**
按照用户定义的consumes生成代码。
**标签值类型** **：**
Boolean
**使用位置** **：**
x-user-defined-consumes（定义在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"
x-interface-name-style: SERVICE_IMPL_AND_NO_I_INTERFACE_PREFIX
x-user-defined-consumes: true
    ----
paths：
  /v1/cards/{card_id}:
    delete:
      tags:
      - "CARD"
      summary: "通过Card的id删除Card"
      description: "Delete a single Card"
      operationId: "DeleteCardById"
      x-is-registered: 'N'
      x-support-sdk: 'N'
      x-method-source: metadata
      x-returnType: Contain<Card>
      # 未在接口中定义consumes标签
      -------
```
**使用效果：**
使用前：
```
@RequestMapping(value = "/v1/cards/{card_id}", consumes= {"*/*"}, method = RequestMethod.DELETE)
    ResponseEntity<Message<Integer>> deleteCardById( @PathVariable("card_id") String cardId);
```
使用后：当path未定义consumes时，不生成consumes。
```
@RequestMapping(value = "/v1/cards/{card_id}", method = RequestMethod.DELETE)
    ResponseEntity<Message<Contain<Card>>> deleteCardById(@PathVariable("card_id") String cardId);
```
#### 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**
![](https://support.huaweicloud.com/usermanual-astropro/public_sys-resources/note_3.0-zh-cn.png)
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的依赖
```