Comment importer plusieurs API conformes à OAS en une seule fois - API Gateway

Importer des définitions d'API conformes à OAS

Le processus d'importation se déroule comme suit :

Sélectionnez le groupe d'API cible et configurez les paramètres globaux.
Saisissez les définitions d'API conformes à OAS 2.0 ou OAS 3.0.
Vérifiez préalablement les définitions d'API et corrigez les problèmes identifiés sur la base des résultats.
Importez les définitions d'API.

Une fois l'importation terminée, les API sont créées dans le groupe d'API spécifié. Vous pouvez ensuite les publier dans l'environnement de votre choix et les déboguer. Pour plus d'informations, consultez la rubrique Déboguer l'API.

Connectez-vous à la console API Gateway.
Dans le volet de navigation de gauche, choisissez Manage APIs > APIs.
Sur la page APIs, cliquez sur Import Swagger-compliant Data.

Dans la boîte de dialogue Note, cliquez sur Standard OAS pour accéder à la page Import Swagger-compliant Data.

Dans la section Basic Information, configurez les paramètres suivants.

Parameter	Description
Import to Group	Spécifiez le groupe d'API dans lequel vous souhaitez importer les API. Important Le chemin de base du groupe d'API doit être identique au chemin de base défini dans vos définitions d'API conformes à OAS. Dans le cas contraire, l'importation des définitions échouera. Pour plus d'informations sur le chemin de base du groupe d'API, consultez la rubrique Créer un groupe d'API. Pour plus d'informations sur le chemin de base dans OAS, consultez la page Swagger Object.
Overwrite	Si vous cochez cette case et que le chemin de la requête entre en conflit avec la requête HTTP, l'API existante est écrasée. Si vous ne cochez pas cette case et que le chemin de la requête entre en conflit avec la requête HTTP, un message d'erreur indiquant que l'API existe déjà s'affiche.
API Definition Version	Les versions OAS 2.0 et OAS 3.0 sont prises en charge.

Dans la section (Optional) Global Configurations, configurez les paramètres globaux des API.

Parameter	Description
Backend Service	Spécifiez un service backend de type HTTP/HTTPS, VPC, Mixed ou Service discovery créé dans API Gateway. La valeur par défaut est Mock. Pour plus d'informations, consultez la rubrique Utiliser un service backend pour créer et gérer des API.
Request Mode	Définissez ce paramètre sur Pass-through ou Map (Filter Out Unknown Parameters). La valeur par défaut est Pass-through. Remarque Si vous utilisez le mode de requête pass-through, seul le paramètre de chemin est importé. API Gateway ignore les autres paramètres, y compris les paramètres query, header, formdata et body.
Caller Authentication	Définissez ce paramètre sur Alibaba Cloud App ou No Authentication. La valeur par défaut est Alibaba Cloud App. Remarque Le service backend, le mode de requête et l'authentification de l'appelant sont des paramètres globaux qui s'appliquent à toutes les API. Si vous utilisez les extensions prises en charge par API Gateway pour déclarer ces paramètres dans les définitions d'API conformes à OAS 2.0, la priorité des paramètres est appliquée dans l'ordre suivant : définitions d'API conformes à OAS 2.0, définitions globales OAS et paramètres globaux facultatifs d'API Gateway. Pour plus d'informations sur les extensions, consultez la section « Importer des définitions d'API conformes à OAS contenant des extensions API Gateway » de cette rubrique. Authentification AppCode : la valeur par défaut est Disable AppCode Authentication si vous définissez Caller Authentication sur Alibaba Cloud App. Algorithme de signature : la valeur par défaut est HMAC_SHA256.

Dans la section API Definition, saisissez les définitions d'API conformes à OAS 2.0 et spécifiez l'une des méthodes d'importation suivantes :

Important
Chaque méthode vous permet d'importer jusqu'à 100 définitions d'API simultanément.
1. Text : saisissez les définitions d'API au format YAML ou JSON. La taille des définitions d'API ne doit pas dépasser 256 Ko.
2. OSS URL : saisissez l'URL de l'objet Object Storage Service (OSS) dans lequel les définitions d'API sont stockées. L'objet doit être au format JSON ou YAML. L'URL de l'objet doit autoriser l'accès anonyme. Aucune limite de taille n'est imposée pour l'objet.

Décidez s'il convient de modifier les paramètres par défaut des autres paramètres dans les définitions d'API. Ces paramètres sont configurés lors de l'importation des définitions d'API, mais ne figurent pas sur la page Import Swagger-compliant Data. Le tableau suivant décrit ces paramètres :

Parameter

Description

Anti-replay Protection

Cette fonctionnalité est désactivée par défaut.

Forbid Internet Access

Cette fonctionnalité est désactivée par défaut.

Allow API Publish to Alibaba Cloud Marketplace

Cette fonctionnalité est désactivée par défaut.

Cliquez sur Precheck. API Gateway effectue une simulation des données que vous souhaitez importer et renvoie les définitions d'API et les définitions de modèle contenues dans les définitions d'API conformes à OAS, ainsi que les avertissements et les erreurs.

Remarque
Avertissements : avant d'importer les définitions d'API, vous pouvez ignorer les avertissements. Dans ce cas, les définitions d'API concernées par les avertissements sont ignorées.

Erreurs : vous devez corriger les erreurs. Sinon, une exception est levée.
Vérifiez qu'aucune erreur ni aucun avertissement n'est présent, puis cliquez sur Import Swagger-compliant Data pour importer les API. Cette opération peut prendre un certain temps. Ne fermez pas votre navigateur avant la fin de l'importation.
Une fois les API importées, vous pouvez consulter le résultat de l'importation.

Correspondances entre les paramètres d'une définition d'API conforme à OAS 2.0 et d'une définition d'API API Gateway

Remarque

Cette section décrit uniquement les paramètres d'une définition d'API conforme à OAS 2.0 qui peuvent être mappés aux paramètres d'une définition d'API API Gateway. Si un paramètre d'une définition d'API conforme à OAS 2.0 ne peut pas être mappé à API Gateway, l'importation de l'API n'est pas affectée.

Objet Swagger
1. BasePath : chemin de base du groupe d'API. Lors de l'importation d'une définition d'API, API Gateway vérifie si le chemin de base de la définition d'API est identique au chemin de base du groupe d'API.
2. Schemes : protocoles de requête définis dans la définition d'API.
Objet Path Item
1. Path : chemin de requête défini dans la définition d'API.
2. Method : méthode de requête définie dans la définition d'API. Valeurs possibles : GET, POST, PUT, HEAD, DELETE, PATCH et OPTIONS.
Objet Operation
1. Summary : description de la définition d'API.
2. OperationId : nom de l'API correspondant à la définition d'API. Si le champ d'extension x-aliyun-apigateway-api-name existe, le nom indiqué dans ce champ d'extension est utilisé comme nom de l'API.
3. Schemes : protocoles de requête définis dans la définition d'API. Les schémas définis dans l'objet Operation ont priorité sur ceux définis dans l'objet Swagger.

Objet Parameter

Name : nom du paramètre de requête défini dans la définition d'API.
In : emplacement du paramètre de requête dans la définition d'API. Valeurs possibles : path, query, head et formdata.
Description : description du paramètre de requête dans la définition d'API.
Required : indique si le paramètre de requête est obligatoire dans la définition d'API.
Type : type du paramètre de requête dans la définition d'API.
1. Valeurs possibles si In est défini sur query, path ou head : string, number, integer, boolean et array.
2. Valeurs possibles si In est défini sur formdata : string, number, integer, boolean, array et file.

Format : format du paramètre de requête dans la définition d'API. Format a priorité sur Type.

Le tableau suivant répertorie les correspondances entre les types de paramètres OAS et les types de paramètres API Gateway.

Parameter type in OAS

Parameter type in API Gateway

String

Boolean

Array

Int32

Int

Int64

Long

Double

Float

File

Remarque

Si vous utilisez le mode de requête pass-through pour une définition d'API, seul le paramètre de chemin est importé dans la définition d'API. API Gateway ignore les autres paramètres, y compris les paramètres query, header, formdata et body.
Si vous utilisez le mode de requête pass-through pour une définition d'API sans utiliser d'extensions API Gateway, assurez-vous que les mêmes valeurs sont spécifiées pour la méthode de requête, le chemin de requête et la définition des paramètres dans les paramètres de requête de la définition d'API et dans le service backend.
Si les paramètres du corps de la requête sont référencés, ils s'affichent lors de la génération de la documentation, mais n'apparaissent pas dans la définition d'API d'API Gateway.

Objet Response
1. HTTP Status Code : code d'état HTTP inclus dans la définition du code d'erreur de la réponse définie dans la définition d'API.
2. Description : description figurant dans la définition du code d'erreur de l'exemple de réponse dans la définition d'API.
3. Schema : modèle inclus dans la définition du code d'erreur de la réponse définie dans la définition d'API.
Objet Definitions

Les objets contenus dans la définition d'API. Lors de l'importation de la définition d'API, API Gateway crée des modèles dans le groupe d'API que vous avez spécifié. Sur la page API Groups, vous pouvez cliquer sur Manage Model dans la colonne Actions du groupe d'API pour afficher les définitions de modèle.

L'exemple de code suivant illustre la définition d'une API conforme à OAS 2.0 afin de vous familiariser avec cette fonctionnalité. Cet exemple utilise la définition d'API de Swagger Petstore.

swagger: "2.0"
info:
  version: "1.0.0"
  title: "Swagger Petstore 2.0"
basePath: "/"
schemes:
- "https"
- "http"
paths:
  /pet/findByStatus:
    get:
      tags:
      - "pet"
      summary: "Finds Pets by status"
      operationId: "findPetsByStatus"
      parameters:
      - name: "status"
        in: "query"
        required: true
        type: "array"
        items:
          type: "string"
          enum:
          - "available"
          - "pending"
          - "sold"
          default: "available"
        collectionFormat: "multi"
      responses:
        "200":
          description: "successful operation"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/Pet"
        "400":
          description: "Invalid status value"
definitions:
  Category:
    type: "object"
    properties:
      id:
        type: "integer"
        format: "int64"
      name:
        type: "string"
  Tag:
    type: "object"
    properties:
      id:
        type: "integer"
        format: "int64"
      name:
        type: "string"
  Pet:
    type: "object"
    required:
    - "name"
    - "photoUrls"
    properties:
      id:
        type: "integer"
        format: "int64"
      category:
        $ref: "#/definitions/Category"
      name:
        type: "string"
        example: "doggie"
      photoUrls:
        type: "array"
        items:
          type: "string"
      tags:
        type: "array"
        items:
          $ref: "#/definitions/Tag"
      status:
        type: "string"
        description: "pet status in the store"
        enum:
        - "available"
        - "pending"
        - "sold"

Correspondances entre les paramètres d'une définition d'API conforme à OAS 3.0 et d'une définition d'API API Gateway

Remarque

Cette section décrit les champs mappés entre une définition d'API conforme à OAS 3.0 et une définition d'API API Gateway. Les champs non mappés n'affectent pas l'importation des API.

Objet Path Item
1. Path : chemin de requête défini dans la définition d'API.
2. Method : méthode de requête définie dans la définition d'API. Valeurs possibles : GET, POST, PUT, HEAD, DELETE, PATCH et OPTIONS.
Objet Operation
1. Summary : description de la définition d'API.
2. OperationId : nom de l'API correspondant à la définition d'API. Si le champ d'extension x-aliyun-apigateway-api-name existe, le nom indiqué dans ce champ d'extension est utilisé comme nom de l'API.
Objet Parameter
1. Name : nom du paramètre de requête défini dans la définition d'API.
2. In : emplacement du paramètre de requête dans la définition d'API. Valeurs possibles : path, query, head et formdata.
3. Required : indique si le paramètre de requête est obligatoire dans la définition d'API.
Objet Schema
1. Description : description du paramètre de requête dans la définition d'API.
2. Type : type du paramètre de requête dans la définition d'API.
  1. Valeurs possibles si In est défini sur query, path ou head : string, number, integer, boolean et array.
  2. Valeurs possibles si In est défini sur formdata : string, number, integer, boolean, array et file.
3. Format : format du paramètre de requête dans la définition d'API. Format a priorité sur Type.
Objet Request Body
1. Content
  1. application/x-www-form-urlencoded : paramètres formdata définis dans la définition d'API.
  2. application/json : pour les objets définis dans cet élément, API Gateway crée le modèle dans le groupe lors de l'importation. Pour afficher la définition du modèle, cliquez sur Manage Model dans la colonne Actions de la ligne correspondant au groupe dans la liste des groupes.
Objet Responses
1. HTTP Status Code : code d'état HTTP inclus dans la définition du code d'erreur de la réponse définie dans la définition d'API.
2. Description : description figurant dans la définition du code d'erreur de l'exemple de réponse dans la définition d'API.
3. Content : modèle inclus dans la définition du code d'erreur de la réponse définie dans la définition d'API.

L'exemple suivant présente une définition conforme à OAS 3.0. Cet exemple utilise la définition de PetStore.

openapi: 3.0.0
info:
  title: Swagger Petstore - OpenAPI 3.0
  version: 1.0.0
paths:
  /pet:
    put:
      tags:
        - pet
      summary: Update an existing pet
      description: Update an existing pet by Id
      operationId: updatePet
      requestBody:
        description: Update an existent pet in the store
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Pet'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'          
        '400':
          description: Invalid ID supplied
        '404':
          description: Pet not found
        '422':
          description: Validation exception
    post:
      tags:
        - pet
      summary: Add a new pet to the store
      description: Add a new pet to the store
      operationId: addPet
      requestBody:
        description: Create a new pet in the store
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Pet'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        '400':
          description: Invalid input
        '422':
          description: Validation exception
  /pet/findByStatus:
    get:
      tags:
        - pet
      summary: Finds Pets by status
      description: Multiple status values can be provided with comma separated strings
      operationId: findPetsByStatus
      parameters:
        - name: status
          in: query
          description: Status values that need to be considered for filter
          required: false
          explode: true
          schema:
            type: string
            default: available
            enum:
              - available
              - pending
              - sold
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'          
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
        '400':
          description: Invalid status value
components:
  schemas:
    Category:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        name:
          type: string
          example: Dogs
      xml:
        name: category
    Tag:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
      xml:
        name: tag
    Pet:
      required:
        - name
        - photoUrls
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
        name:
          type: string
          example: doggie
        category:
          $ref: '#/components/schemas/Category'
        photoUrls:
          type: array
          xml:
            wrapped: true
          items:
            type: string
            xml:
              name: photoUrl
        tags:
          type: array
          xml:
            wrapped: true
          items:
            $ref: '#/components/schemas/Tag'
        status:
          type: string
          description: pet status in the store
          enum:
            - available
            - pending
            - sold
      xml:
        name: pet

Importer des définitions d'API conformes à OAS 2.0 contenant des extensions API Gateway

Pour plus d'informations, consultez la rubrique Exporter des API basées sur OAS.