Tous les produits
Search

Ce produit

    API Gateway:Importer une définition Swagger étendue

    Centre de documentation

    API Gateway:Importer une définition Swagger étendue

    Dernière mise à jour :Aug 25, 2026

    Les extensions Swagger d'API Gateway sont basées sur Swagger 2.0. Utilisez ces extensions pour rédiger les définitions Swagger de vos API, puis importez le fichier Swagger dans API Gateway afin de créer ou de mettre à jour des API par lots. API Gateway est préconfiguré pour Swagger 2.0 et prend en charge la majeure partie de la spécification Swagger, bien que certaines différences subsistent.

    Méthodes d'importation Swagger

    Swagger est une spécification permettant de décrire les définitions d'API. Elle est largement utilisée pour définir et décrire les API des services d'applications backend. API Gateway prend en charge l'importation d'un fichier Swagger 2.0 pour créer des API. Appelez l'opération ImportSwagger ou effectuez cette opération depuis la console.

    Dans le volet de navigation de gauche de la console API Gateway, choisissez API Management > API List. Ensuite, cliquez sur Import Swagger dans le coin supérieur droit de la page.

    Les sections suivantes décrivent les extensions API Gateway pour Swagger et fournissent des exemples illustrant leur utilisation.

    Important

    Tous les paramètres et valeurs dans Swagger sont sensibles à la casse.

    Extensions Swagger

    Les extensions Swagger d'API Gateway étendent principalement l'objet natif Operation Object de Swagger pour ajouter des fonctionnalités d'authentification, de mappage de paramètres et de service backend. Une extension pour la méthode ANY est également fournie afin de capturer les requêtes HTTP utilisant n'importe quelle méthode. Toutes les extensions commencent par x-aliyun-apigateway-. Les sections suivantes décrivent chaque extension.

    Prise en charge de la portée globale

    Les extensions suivantes prennent en charge les définitions au niveau de la portée globale. Si une extension n'est pas définie dans sa propre portée, la valeur définie au niveau global est automatiquement appliquée. Si l'extension est définie dans sa propre portée, la valeur de cette portée est prioritaire.

    • x-aliyun-apigateway-backend

    • x-aliyun-apigateway-api-market-enable

    • x-aliyun-apigateway-api-force-nonce-check

    • x-aliyun-apigateway-parameter-handling

    • x-aliyun-apigateway-auth-type

    x-aliyun-apigateway-auth-type : Type d'autorisation

    x-aliyun-apigateway-auth-type s'applique à l'objet Operation Object et spécifie le type d'autorisation de l'API.

    Valeurs valides :

    • APP (par défaut) : autorisation d'application par Alibaba Cloud API Gateway.

    • ANONYMOUS : accès anonyme. Exemple :

    ...
paths:
  'path/':
    get:
      x-aliyun-apigateway-auth-type: ANONYMOUS
...

    x-aliyun-apigateway-api-market-enable : Prise en charge d'Alibaba Cloud Marketplace

    x-aliyun-apigateway-api-market-enable s'applique à l'objet Operation Object et indique si l'API peut être publiée sur Alibaba Cloud Marketplace.

    Valeurs valides :

    • true

    • false (par défaut). Exemple :

    ...
paths:
  'path/':
    get:
      x-aliyun-apigateway-api-market-enable: true
...

    x-aliyun-apigateway-api-force-nonce-check : Vérification NONCE

    x-aliyun-apigateway-api-force-nonce-check s'applique à l'objet Operation Object et indique s'il faut appliquer une vérification NONCE pour l'API.

    Valeurs valides :

    • true

    • false (par défaut). Exemple :

    ...
paths:
  'path/':
    get:
      x-aliyun-apigateway-api-force-nonce-check: true
...

    x-aliyun-apigateway-parameter-handling : Mappage des paramètres

    x-aliyun-apigateway-parameter-handling s'applique à l'objet Operation Object et spécifie comment les paramètres de requête sont mappés aux paramètres du service backend. Si la relation de mappage est définie sur PASSTHROUGH, l'objet Parameter Object ne prend pas en charge les propriétés x-aliyun-apigateway-backend-location et x-aliyun-apigateway-backend-name.

    Valeurs valides :

    • PASSTHROUGH (par défaut) : transmet les paramètres de requête tels quels.

    • MAPPING : mappe les paramètres de requête. Exemple :

    ...
paths:
  'path/':
    get:
      x-aliyun-apigateway-parameter-handling: MAPPING
...

    x-aliyun-apigateway-backend : Type de service backend

    x-aliyun-apigateway-backend s'applique à l'objet Operation Object et configure les informations relatives au service backend. Les propriétés disponibles dépendent du type de service backend, comme décrit dans les sections suivantes.

    Type de service backend : HTTP

    Utilisez le type de service backend HTTP pour configurer directement l'adresse du service backend. Ce type est généralement utilisé lorsque l'adresse backend est directement accessible.

    Le tableau suivant décrit les propriétés du type de service backend HTTP.

    Propriété Type Description
    type string Obligatoire. La valeur est HTTP.
    address string Obligatoire. Identifie l'adresse du service backend.
    path string Facultatif. Identifie le chemin d'accès du service backend. Les variables de chemin sont prises en charge. Par défaut, cette valeur est identique au chemin racine.
    method string Obligatoire. La méthode de requête backend.
    timeout int Facultatif. Valeur par défaut : 10000. Valeurs valides : 500 à 30000.

    Exemple :

    ...
x-aliyun-apigateway-backend:
  type: HTTP
  address: 'http://www.aliyun.com'
  path: '/builtin/echo'
  method: get
  timeout: 10000
...

    Type de service backend : HTTP-VPC

    Utilisez le type de service backend HTTP-VPC lorsque le service backend réside dans un VPC. Vous devez d'abord créer une autorisation VPC, puis importer l'autorisation par son nom. Pour plus d'informations, consultez la rubrique Création d'une API utilisant une ressource dans un VPC comme service backend.

    Le tableau suivant décrit les propriétés du type de service backend HTTP-VPC.

    Propriété Type Description
    type string Obligatoire. La valeur est HTTP-VPC.
    vpcAccessName string Obligatoire. Le nom de l'instance connectée au VPC utilisée par le service backend.
    path string Facultatif. Identifie le chemin d'accès du service backend. Les variables de chemin sont prises en charge. Par défaut, cette valeur est identique au chemin racine.
    method string Obligatoire. La méthode de requête backend.
    timeout int Facultatif. Valeur par défaut : 10000. Valeurs valides : 500 à 30000.

    Exemple :

    ...
x-aliyun-apigateway-backend:
  type: HTTP-VPC
  vpcAccessName: vpcAccess1
  path: '/users/{userId}'
  method: GET
  timeout: 10000
...

    Type de service backend : FC

    Utilisez le type de service backend FC lorsque le service backend d'API Gateway est Function Compute.

    Le tableau suivant décrit les propriétés du type de service backend FC.

    Propriété Type Description
    type string Obligatoire. La valeur est FC.
    fcRegion string Obligatoire. La région dans laquelle réside Function Compute.
    serviceName string Obligatoire. Le nom du service Function Compute.
    functionName string Obligatoire. Le nom de la fonction Function Compute.
    arn string Facultatif. L'autorisation RAM pour Function Compute.

    Exemple :

    ...
x-aliyun-apigateway-backend:
  type: FC
  fcRegion: cn-shanghai
  serviceName: fcService
  functionName: fcFunction
  arn: acs:ram::111111111:role/aliyunapigatewayaccessingfcrole
...

    Type de service backend : MOCK

    Utilisez le type de service backend MOCK pour simuler la réponse que vous avez prédéfinie.

    Le tableau suivant décrit les propriétés du type de service backend MOCK.

    Propriété Type Description
    type string Obligatoire. La valeur est MOCK.
    mockResult string Obligatoire. La réponse simulée.
    mockStatusCode integer Facultatif.
    mockHeaders Header Facultatif.

    Le tableau suivant décrit les propriétés du type Header.

    Propriété Type Description
    name string Obligatoire.
    value string Obligatoire.

    Exemple :

    ...
x-aliyun-apigateway-backend:
  type: MOCK
  mockResult: mock resul sample
  mockStatusCode: 200
  mockHeaders:
    - name: server
      value: mock
    - name: proxy
      value: GW
...

    x-aliyun-apigateway-constant-parameters : Paramètres constants

    x-aliyun-apigateway-constant-parameters s'applique à l'objet Operation Object et définit les paramètres constants du service backend.

    Le tableau suivant décrit les propriétés d'un paramètre constant.

    Propriété Type Description
    backendName string Obligatoire. Le nom du paramètre backend.
    value string Obligatoire. La valeur constante.
    location string Obligatoire. L'emplacement où le paramètre constant est stocké. Valeurs valides : query et header.
    description string Facultatif. Décrit la constante.

    Exemple :

    ...
x-aliyun-apigateway-constant-parameters:
  - backendName: swaggerConstant
    value: swaggerConstant
    location: header
    description: description of swagger
...

    x-aliyun-apigateway-system-parameters : Paramètres système backend

    x-aliyun-apigateway-system-parameters s'applique à l'objet Operation Object et définit les paramètres système du service backend de l'API.

    Le tableau suivant décrit les propriétés d'un paramètre système backend.

    Propriété Type Description
    systemName string Obligatoire. Le nom du paramètre système.
    backendName string Obligatoire. Le nom du paramètre backend.
    location string Obligatoire. L'emplacement où le paramètre constant est stocké. Valeurs valides : query et header.

    Exemple :

    ...
x-aliyun-apigateway-system-parameters:
  - systemName: CaAppId
    backendName: appId
    location: header
...

    x-aliyun-apigateway-backend-location : Emplacement du paramètre backend

    x-aliyun-apigateway-backend-location s'applique à l'objet Parameter Object et spécifie l'emplacement du paramètre dans la requête du service backend après le mappage des paramètres. Cette propriété prend effet uniquement lorsque x-aliyun-apigateway-parameter-handling: MAPPING est défini.

    Valeurs valides :

    • path

    • header

    • query

    • formData Exemple :

    ...
parameters:
  - name: swaggerHeader
    in: header
    required: false
    type: number
    format: double
    minimum: 0.1
    maximum: 0.5
    x-aliyun-apigateway-backend-location: query
    x-aliyun-apigateway-backend-name: backendQuery
...

    x-aliyun-apigateway-backend-name : Nom du paramètre backend

    x-aliyun-apigateway-backend-name s'applique à l'objet Parameter Object et spécifie le nom du paramètre dans la requête du service backend après le mappage des paramètres. Cette propriété prend effet uniquement lorsque x-aliyun-apigateway-parameter-handling: MAPPING est défini.

    Exemple :

    ...
parameters:
  - name: swaggerHeader
    in: header
    required: false
    type: number
    format: double
    minimum: 0.1
    maximum: 0.5
    x-aliyun-apigateway-backend-location: query
    x-aliyun-apigateway-backend-name: backendQuery
...

    x-aliyun-apigateway-query-schema : Schéma de paramètre de requête

    x-aliyun-apigateway-query-schema s'applique à l'objet Parameter Object et définit un modèle pour un paramètre de requête. Vous pouvez utiliser cette extension lorsqu'un paramètre est de type String et est défini comme paramètre de requête.

    Exemple :

    ...
parameters:
  - name: event_info
    in: query
    required: true
    type: string
    x-aliyun-apigateway-query-schema:
      $ref: "#/definitions/EvnetInfo"
...

    x-aliyun-apigateway-any-method : Méthode ANY

    x-aliyun-apigateway-any-method s'applique à l'objet Path Item Object et permet à l'API d'accepter des requêtes HTTP de tout type.

    Exemple :

    ...
paths:
  'path/':
    x-aliyun-apigateway-any-method:
    ...
...

    x-aliyun-apigateway-app-code-type : Authentification AppCode

    x-aliyun-apigateway-app-code-type s'applique à l'objet Operation Object et indique si l'API prend en charge l'authentification AppCode.

    Valeurs valides :

    • DEFAULT (par défaut)

    • DISABLE : désactive l'authentification AppCode.

    • HEADER : transmet l'AppCode dans un en-tête de requête.

    • HEADER_QUERY : transmet l'AppCode dans un en-tête de requête ou un paramètre de requête. Exemple :

    ...
paths:
  'path/':
    get:
      x-aliyun-apigateway-app-code-type: HEADER
...

    Différences par rapport à la spécification Swagger

    API Gateway et la spécification Swagger diffèrent sur les points suivants lors de la définition des API. Ces différences affectent directement l'utilisation de la fonctionnalité d'importation Swagger.

    Mappage entre les types de paramètres Swagger et les types originaux d'API Gateway

    Type Swagger Type API Gateway Paramètres et règles de validation pris en charge
    type: integer, format: int32 Int minimum, maximum
    type: integer, format: int64 Long minimum, maximum
    type: number, format: float Float minimum, maximum
    type: number, format: double Double minimum, maximum
    type: string String maxLength, enumValues, pattern
    type: boolean, format: boolean Boolean -

    Prise en charge du champ consumes

    Si un fichier de configuration Swagger contient des paramètres formData, vous devez configurer le nœud consumes. API Gateway prend actuellement en charge uniquement le type application/x-www-form-urlencoded.

    consumes:
  - application/x-www-form-urlencoded

    Restrictions sur les définitions Swagger

    L'importation Swagger prend en charge les définitions de modèles, mais l'implémentation diffère de la spécification Swagger originale. Les définitions de modèles sont principalement utilisées pour générer des kits de développement logiciel (SDK). Par conséquent, les restrictions suivantes s'ajoutent à la spécification Swagger originale :

    • La balise schema dans Swagger prend en charge uniquement le type $ref.

    • Un modèle dans la section definitions de Swagger prend en charge uniquement les définitions de modèles de type objet.

    • Si un modèle dans la section definitions de Swagger contient une définition de tableau, la référence $ref doit être utilisée conjointement avec la balise title. Par défaut, un type tableau est généré sous forme d'ArrayList lors de la génération du SDK.

    Exemples Swagger

    Les exemples suivants sont des définitions Swagger complètes utilisant les extensions Swagger d'API Gateway. Utilisez-les comme point de départ lorsque vous définissez vos propres API.

    Remarque

    Les exemples sont fournis à titre indicatif uniquement.

    Exemple Swagger : Service backend HTTP

    swagger: '2.0'
basePath: /
info:
  version: '0.9'
  title: Aliyun Api Gateway Swagger Sample
schemes:
  - http
  - https
x-aliyun-apigateway-parameter-handling: MAPPING
x-aliyun-apigateway-api-market-enable: true
x-aliyun-apigateway-api-force-nonce-check: true
x-aliyun-apigateway-backend:
  type: HTTP
  address: 'http://www.aliyun.com'
  method: get
  timeout: 10000
paths:
  '/http/get/mapping/{userId}':
    get:
      operationId: case1
      schemes:
        - http
        - https
      x-aliyun-apigateway-parameter-handling: MAPPING
      x-aliyun-apigateway-api-market-enable: true
      x-aliyun-apigateway-auth-type: ANONYMOUS
      parameters:
        - name: userId
          in: path
          required: true
          type: string
        - name: swaggerQuery
          in: query
          required: false
          default: '123465'
          type: integer
          format: int32
          minimum: 0
          maximum: 100
        - name: swaggerHeader
          in: header
          required: false
          type: number
          format: double
          minimum: 0.1
          maximum: 0.5
          x-aliyun-apigateway-backend-location: query
          x-aliyun-apigateway-backend-name: backendQuery
      x-aliyun-apigateway-constant-parameters:
        - backendName: swaggerConstant
          value: swaggerConstant
          location: header
          description: description of swagger
      x-aliyun-apigateway-system-parameters:
        - systemName: CaAppId
          backendName: appId
          location: header
      responses:
        '200':
          description: 200 description
        '400':
          description: 400 description
  '/echo/test/post/{userId}':
    post:
      operationId: testpost
      schemes:
        - http
        - https
      x-aliyun-apigateway-parameter-handling: MAPPING
      x-aliyun-apigateway-backend:
        type: HTTP
        address: 'http://www.aliyun.com'
        method: post
        timeout: 10000
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - name: userId
          required: true
          in: path
          type: string
        - name: swaggerQuery1
          in: query
          required: false
          default: '123465'
          type: integer
          format: int32
          minimum: 0
          maximum: 100
          x-aliyun-apigateway-enum: 1,2,3
        - name: swaggerQuery2
          in: query
          required: false
          type: string
          x-aliyun-apigateway-backend-location: header
          x-aliyun-apigateway-backend-name: backendHeader
          x-aliyun-apigateway-query-schema:
            $ref: '#/definitions/AiGeneratePicQueryVO'
        - name: swaggerHeader
          in: header
          required: false
          type: number
          format: double
          minimum: 0.1
          maximum: 0.5
          x-aliyun-apigateway-backend-location: query
          x-aliyun-apigateway-backend-name: backendQuery
        - name: swaggerFormdata
          in: formData
          required: true
          type: string
      responses:
        '200':
          description: 200 description
          schema:
            $ref: '#/definitions/ResultOfGeneratePicturesVO'
        '400':
          description: 400 description
    x-aliyun-apigateway-any-method:
      operationId: case2
      schemes:
        - http
        - https
      x-aliyun-apigateway-parameter-handling: MAPPING
      x-aliyun-apigateway-backend:
        type: HTTP
        address: 'http://www.aliyun.com'
        path: '/builtin/echo/{abc}'
        method: post
        timeout: 10000
      parameters:
        - name: userId
          in: path
          required: false
          default: '123465'
          type: integer
          format: int32
          minimum: 0
          maximum: 100
          x-aliyun-apigateway-backend-name: abc
          x-aliyun-apigateway-backend-location: path
      responses:
        '200':
          description: 200 description
        '400':
          description: 400 description
definitions:
  AiGeneratePicQueryVO:
    type: object
    properties:
      transactionId:
        type: string
        description: asynchronous task ID
  GeneratePictureVO:
    type: object
    properties:
      id:
        type: integer
        format: int64
        description: image ID
      name:
        type: string
        description: image name
  GeneratePicturesVO:
    type: object
    properties:
      failSize:
        type: integer
        format: int64
        description: number of failures
      list:
        type: array
        description: image list
        items:
          $ref: '#/definitions/GeneratePictureVO'
          title: GeneratePictureVO
      successSize:
        type: integer
        format: int32
        description: number of successes
      totalSize:
        type: number
        format: float
        description: total number of requests
  ResultOfGeneratePicturesVO:
    type: object
    properties:
      model:
        description: response content
        $ref: '#/definitions/GeneratePicturesVO'
        title: GeneratePicturesVO
      requestId:
        type: string
        description: request ID

    Exemple Swagger : Service backend HTTP-VPC

    swagger: '2.0'
basePath: /
info:
  version: '0.9'
  title: Aliyun Api Gateway Swagger Sample
schemes:
  - http
  - https
paths:
  '/http/get/mapping/{userId}':
    get:
      operationId: case1
      schemes:
        - http
        - https
      x-aliyun-apigateway-parameter-handling: MAPPING
      x-aliyun-apigateway-backend:
        type: HTTP-VPC
        vpcAccessName: vpcName1
        path: '/builtin/echo/{userId}'
        method: get
        timeout: 10000
      parameters:
        - name: userId
          in: path
          required: true
          type: string
        - name: swaggerQuery
          in: query
          required: false
          default: '123465'
          type: integer
          format: int32
          minimum: 0
          maximum: 100
        - name: swaggerHeader
          in: header
          required: false
          type: number
          format: double
          minimum: 0.1
          maximum: 0.5
          x-aliyun-apigateway-backend-location: query
          x-aliyun-apigateway-backend-name: backendQuery
      responses:
        '200':
          description: 200 description
        '400':
          description: 400 description
  '/echo/test/post':
    post:
      operationId: testpost
      schemes:
        - http
        - https
      x-aliyun-apigateway-parameter-handling: MAPPING
      x-aliyun-apigateway-backend:
        type: HTTP-VPC
        vpcAccessName: vpcName2
        path: '/builtin/echo'
        method: post
        timeout: 10000
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - name: swaggerQuery1
          in: query
          required: false
          default: '123465'
          type: integer
          format: int32
          minimum: 0
          maximum: 100
        - name: swaggerQuery2
          in: query
          required: false
          type: string
          x-aliyun-apigateway-backend-location: header
          x-aliyun-apigateway-backend-name: backendHeader
        - name: swaggerHeader
          in: header
          required: false
          type: number
          format: double
          minimum: 0.1
          maximum: 0.5
          x-aliyun-apigateway-backend-location: query
          x-aliyun-apigateway-backend-name: backendQuery
        - name: swaggerFormdata
          in: formData
          required: true
          type: string
      responses:
        '200':
          description: 200 description
        '400':
          description: 400 description
    x-aliyun-apigateway-any-method:
      operationId: case2
      schemes:
        - http
        - https
      x-aliyun-apigateway-parameter-handling: PASSTHROUGH
      x-aliyun-apigateway-backend:
        type: HTTP-VPC
        vpcAccessName: vpcName3
        path: '/builtin/echo'
        method: post
        timeout: 10000
      responses:
        '200':
          description: 200 description
        '400':
          description: 400 description

    Exemple Swagger : Service backend Function Compute

    swagger: '2.0'
basePath: /
info:
  version: '0.9'
  title: Aliyun Api Gateway Swagger Sample
schemes:
  - http
  - https
paths:
  '/http/get/mapping/{userId}':
    get:
      operationId: case1
      schemes:
        - http
        - https
      x-aliyun-apigateway-parameter-handling: MAPPING
      x-aliyun-apigateway-backend:
        type: FC
        fcRegion: cn-shanghai
        serviceName: fcService
        functionName: fcFunction
        arn: acs:ram::111111111:role/aliyunapigatewayaccessingfcrole
      parameters:
        - name: userId
          in: path
          required: true
          type: string
      responses:
        '200':
          description: 200 description
        '400':
          description: 400 description

    Exemple Swagger : Service backend MOCK

    swagger: '2.0'
basePath: /
info:
  version: '0.9'
  title: Aliyun Api Gateway Swagger Sample
schemes:
  - http
paths:
  '/mock/get/mapping/{userId}':
    get:
      operationId: case1
      schemes:
        - http
        - https
      x-aliyun-apigateway-parameter-handling: MAPPING
      x-aliyun-apigateway-backend:
        type: MOCK
        mockResult: mock resul sample
        mockStatusCode: 200
        mockHeaders:
          - name: server
            value: mock
          - name: proxy
            value: GW
      parameters:
        - name: userId
          in: path
          required: true
          type: string
      responses:
        '200':
          description: 200 description
        '400':
          description: 400 description