Tüm Ürünler
Search
Belge Merkezi

API Gateway:OAS uyumlu API'leri içe aktarma

Son Güncelleme:Oct 04, 2026

API Gateway, OpenAPI Specification (OAS) 2,0 veya 3,0 formatındaki API tanımlarını içe aktarmayı destekler. Daha fazla bilgi için bkz. OpenAPI Specification. Standart OAS tanımlarını veya API Gateway uzantıları içeren OAS tanımlarını içe aktarabilirsiniz.

OAS uyumlu API tanımlarını içe aktarma

İçe aktarma süreci şu adımları içerir:

  • Hedef API grubunu seçin ve genel ayarları yapılandırın.

  • OAS 2,0 veya OAS 3,0 uyumlu API tanımlarını girin.

  • API tanımlarını ön kontrol edin ve sonuçlara göre sorunları düzeltin.

  • API tanımlarını içe aktarın.

İçe aktarma işleminden sonra API'ler belirtilen API grubunda oluşturulur. Ardından bu API'leri tercih ettiğiniz ortama yayınlayabilir ve hata ayıklayabilirsiniz. Daha fazla bilgi için bkz. API'de hata ayıklama.

  1. API Gateway konsoluna giriş yapın.

  2. Sol gezinme bölmesinde Manage APIs > APIs seçeneklerini belirleyin.

  3. APIs sayfasında Import Swagger-compliant Data seçeneğine tıklayın.

  4. Not iletişim kutusunda, Import Swagger-compliant Data sayfasına gitmek için Standard OAS seçeneğine tıklayın.

    1. Basic Information bölümünde aşağıdaki parametreleri yapılandırın.

      Parameter

      Description

      Import to Group

      API'leri içe aktarmak istediğiniz API grubunu belirtin.

      Önemli

      API grubunun temel yolu, OAS uyumlu API tanımlarınızdaki temel yol ile aynı olmalıdır. Aksi takdirde tanımlar içe aktarılamaz. API grubunun temel yolu hakkında daha fazla bilgi için bkz. API grubu oluşturma. OAS'teki temel yol hakkında daha fazla bilgi için bkz. Swagger Object.

      Overwrite

      • Onay kutusunu seçerseniz ve istek yolu HTTP isteğiyle çakışıyorsa mevcut API'nin üzerine yazılır.

      • Onay kutusunu seçmezseniz ve istek yolu HTTP isteğiyle çakışıyorsa API'nin zaten var olduğunu belirten bir hata mesajı döndürülür.

      API Definition Version

      OAS 2,0 ve OAS 3,0 desteklenir.

    2. (Optional) Global Configurations bölümünde API'ler için genel ayarları yapılandırın.

      Parameter

      Description

      Backend Service

      API Gateway'de oluşturulmuş HTTP/HTTPS, VPC, Mixed veya Service discovery türünde bir backend service belirtin. Varsayılan değer Mock'tur. Daha fazla bilgi için bkz. API'leri oluşturmak ve yönetmek için backend service kullanma.

      Request Mode

      Bu parametreyi Pass-through veya Map (Filter Out Unknown Parameters) olarak ayarlayın. Varsayılan değer Pass-through'dur.

      Not

      Pass-through istek modunu kullanırsanız yalnızca path parametresi içe aktarılır. API Gateway query, header, formdata ve body parametreleri dahil diğer tüm parametreleri yoksayar.

      Caller Authentication

      Bu parametreyi Alibaba Cloud App veya No Authentication olarak ayarlayın. Varsayılan değer Alibaba Cloud App'tir.

      Not
      • Backend service, request mode ve caller authentication, tüm API'ler için geçerli olan genel ayarlardır. OAS 2,0 uyumlu API tanımlarında ayarları bildirmek için API Gateway tarafından desteklenen uzantıları kullanırsanız ayarlar şu öncelik sırasına göre uygulanır: OAS 2,0 uyumlu API tanımları, OAS genel tanımları ve API Gateway'in isteğe bağlı genel ayarları. Uzantılar hakkında daha fazla bilgi için bu konunun "API Gateway uzantıları içeren OAS uyumlu API tanımlarını içe aktarma" bölümüne bakın.

      • AppCode Authentication: Caller Authentication öğesini Alibaba Cloud App olarak ayarlarsanız varsayılan değer Disable AppCode Authentication'dır. Signature Algorithm: Varsayılan değer HMAC_SHA256'dır.

    3. API Definition bölümünde OAS 2,0 uyumlu API tanımlarını girin ve aşağıdaki içe aktarma yöntemlerinden birini belirtin:

      Önemli

      Her yöntemle aynı anda en fazla 100 API tanımı içe aktarabilirsiniz.

      1. Text: API tanımlarını YAML veya JSON formatında girin. API tanımlarının uzunluğu en fazla 256 KB olabilir.

      2. OSS URL: API tanımlarının depolandığı Object Storage Service (OSS) nesnesinin URL'sini girin. Nesne JSON veya YAML formatında olmalıdır. Nesne URL'si anonim erişimi desteklemelidir. Nesne boyutu üzerinde herhangi bir sınır yoktur.

  5. API tanımlarındaki diğer parametrelerin varsayılan ayarlarını değiştirip değiştirmeyeceğinize karar verin. Bu parametreler API tanımlarını içe aktarırken yapılandırılır ancak Import Swagger-compliant Data sayfasında sağlanmaz. Parametreler aşağıdaki tabloda açıklanmıştır:


    Parameter


    Description


    Anti-replay Protection


    Bu özellik varsayılan olarak devre dışı bırakılmıştır.


    Forbid Internet Access


    Bu özellik varsayılan olarak devre dışı bırakılmıştır.


    Allow API Publish to Alibaba Cloud Marketplace


    Bu özellik varsayılan olarak devre dışı bırakılmıştır.

  6. Precheck seçeneğine tıklayın. API Gateway, içe aktarmak istediğiniz veriler üzerinde bir deneme çalıştırması gerçekleştirir ve OAS uyumlu API tanımlarındaki API tanımları ile model tanımlarını, uyarıları ve hataları döndürür.

    Not

    Uyarılar: API tanımlarını içe aktarmadan önce uyarıları yok sayabilirsiniz. Bu durumda uyarı içeren API tanımları yoksayılır.

    Hatalar: Hataları düzeltmeniz gerekir. Aksi takdirde bir özel durum oluşur.

  7. Hata ve uyarı bulunmadığını onaylayın ve API'leri içe aktarmak için Import Swagger-compliant Data seçeneğine tıklayın. Bu işlem biraz zaman alabilir. İçe aktarma tamamlanana kadar tarayıcınızı kapatmayın.

  8. API'ler içe aktarıldıktan sonra API'lerin içe aktarma sonucunu görüntüleyebilirsiniz.

OAS 2,0 uyumlu bir API tanımındaki parametreler ile API Gateway API tanımı arasındaki eşlemeler

Not

Bu bölümde yalnızca API Gateway API tanımındaki parametrelerle eşlenebilen OAS 2,0 uyumlu API tanımındaki parametreler açıklanmaktadır. OAS 2,0 uyumlu bir API tanımındaki bir parametre API Gateway ile eşlenemezse API'nin içe aktarılması etkilenmez.

  1. Swagger Object

    1. BasePath: API grubunun temel yoludur. Bir API tanımını içe aktardığınızda API Gateway, API tanımının temel yolunun API grubunun temel yoluyla aynı olup olmadığını kontrol eder.

    2. Schemes: API tanımındaki istek protokolleridir.

  2. Path Item Object

    1. Path: API tanımındaki istek yoludur.

    2. Method: API tanımındaki istek yöntemidir. Geçerli değerler: GET, POST, PUT, HEAD, DELETE, PATCH ve OPTIONS.

  3. Operation Object

    1. Summary: API tanımının açıklamasıdır.

    2. OperationId: API tanımına karşılık gelen API'nin adıdır. x-aliyun-apigateway-api-name uzantı alanı varsa uzantı alanındaki ad API'nin adı olarak kullanılır.

    3. Schemes: API tanımındaki istek protokolleridir. Operation Object içindeki Schemes, Swagger Object içindeki Schemes'e göre önceliklidir.

  4. Parameter Object

    1. Name: API tanımındaki istek parametresinin adıdır.

    2. In: API tanımındaki istek parametresinin konumudur. Geçerli değerler: path, query, head ve formdata.

    3. Description: API tanımındaki istek parametresinin açıklamasıdır.

    4. Required: API tanımındaki istek parametresinin gerekli olup olmadığını belirtir.

    5. Type: API tanımındaki istek parametresinin türüdür.

      1. In değeri query, path veya head olarak ayarlandığında geçerli değerler: string, number, integer, boolean ve array.

      2. In değeri formdata olarak ayarlandığında geçerli değerler: string, number, integer, boolean, array ve file.

    6. Format: API tanımındaki istek parametresinin formatıdır. Format, Type'a göre önceliklidir.

      Aşağıdaki tabloda OAS'teki parametre türleri ile API Gateway'deki parametre türleri arasındaki eşlemeler listelenmiştir.


      Parameter type in OAS


      Parameter type in API Gateway


      String


      String


      Boolean


      Boolean


      Array


      Array


      Int32


      Int


      Int64


      Long


      Double


      Double


      Float


      Float


      File


      File

      Not
      1. Bir API tanımı için pass-through istek modunu kullanırsanız API tanımına yalnızca path parametresi içe aktarılır. API Gateway query, header, formdata ve body parametreleri dahil diğer tüm parametreleri yoksayar.

      2. Bir API tanımı için pass-through istek modunu kullanır ve API Gateway uzantılarını kullanmazsanız API tanımının istek parametrelerindeki istek yöntemi, istek yolu ve parametre tanımı ile backend service'teki değerlerin aynı olduğundan emin olun.

      3. İstek gövdesindeki parametrelere referans verilirse parametreler belge oluşturulurken görüntülenir ancak API Gateway'in API tanımında görüntülenmez.

  5. Response Object

    1. HTTP Status Code: API tanımında tanımlanan yanıtın hata kodu tanımında yer alan HTTP durum kodudur.

    2. Description: API tanımındaki örnek yanıtta yer alan hata kodu tanımındaki açıklamadır.

    3. Schema: API tanımında tanımlanan yanıtın hata kodu tanımında yer alan modeldir.

  6. Definitions Object

    API tanımındaki nesnelerdir. API tanımını içe aktardığınızda API Gateway, belirttiğiniz API grubunda modeller oluşturur. API Groups sayfasında API grubunun Actions sütunundaki Manage Model seçeneğine tıklayarak model tanımlarını görüntüleyebilirsiniz.

  7. Aşağıdaki örnek kod, bu özelliğe aşina olmanıza yardımcı olmak amacıyla OAS 2,0 uyumlu bir API tanımının nasıl tanımlanacağını göstermektedir. Bu örnekte Swagger Petstore'un API tanımı kullanılmıştır.

    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"

OAS 3,0 uyumlu bir API tanımındaki parametreler ile API Gateway API tanımı arasındaki eşlemeler

Not

Bu bölümde OAS 3,0 uyumlu bir API tanımı ile API Gateway API tanımı arasındaki eşlenen alanlar açıklanmaktadır. Eşlenmemiş alanlar API içe aktarma işlemini etkilemez.

  1. Path Item Object

    1. Path: API tanımındaki istek yoludur.

    2. Method: API tanımındaki istek yöntemidir. Geçerli değerler: GET, POST, PUT, HEAD, DELETE, PATCH ve OPTIONS.

  2. Operation Object

    1. Summary: API tanımının açıklamasıdır.

    2. OperationId: API tanımına karşılık gelen API'nin adıdır. x-aliyun-apigateway-api-name uzantı alanı varsa uzantı alanındaki ad API'nin adı olarak kullanılır.

  3. Parameter Object

    1. Name: API tanımındaki istek parametresinin adıdır.

    2. In: API tanımındaki istek parametresinin konumudur. Geçerli değerler: path, query, head ve formdata.

    3. Required: API tanımındaki istek parametresinin gerekli olup olmadığını belirtir.

  4. Schema Object

    1. Description: API tanımındaki istek parametresinin açıklamasıdır.

    2. Type: API tanımındaki istek parametresinin türüdür.

      1. In değeri query, path veya head olarak ayarlandığında geçerli değerler: string, number, integer, boolean ve array.

      2. In değeri formdata olarak ayarlandığında geçerli değerler: string, number, integer, boolean, array ve file.

    3. Format: API tanımındaki istek parametresinin formatıdır. Format, Type'a göre önceliklidir.

  5. Request Body Object

    1. Content

      1. application/x-www-form-urlencoded: API tanımındaki formdata parametreleridir.

      2. application/json: Bu öğede tanımlanan nesneler için API Gateway içe aktarma sırasında grupta modeli oluşturur. Model tanımını görüntülemek için grup listesindeki grubun bulunduğu satırın Actions sütunundaki Manage Model seçeneğine tıklayın.

  6. Responses Object

    1. HTTP Status Code: API tanımında tanımlanan yanıtın hata kodu tanımında yer alan HTTP durum kodudur.

    2. Description: API tanımındaki örnek yanıtta yer alan hata kodu tanımındaki açıklamadır.

    3. Content: API tanımında tanımlanan yanıtın hata kodu tanımındaki modeldir.

  7. Aşağıdaki örnek OAS 3,0 uyumlu bir tanımı göstermektedir. Bu örnekte PetStore tanımı kullanılmıştır.

    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

API Gateway uzantıları içeren OAS 2,0 uyumlu API tanımlarını içe aktarma

Daha fazla bilgi için bkz. OAS tabanlı API'leri dışa aktarma.