Tüm Ürünler
Search
Belge Merkezi

API Gateway:Gelişmiş Swagger tanımı içe aktarma

Son Güncelleme:Oct 04, 2026

API Gateway'in Swagger uzantıları Swagger 2.0 tabanlıdır. Bu uzantıları kullanarak API'leriniz için Swagger tanımları yazabilir ve ardından Swagger dosyasını API Gateway'e içe aktararak API'leri toplu olarak oluşturup güncelleyebilirsiniz. API Gateway, Swagger 2.0 için önceden yapılandırılmıştır ve Swagger belirtiminin büyük bölümünü destekler; ancak bazı farklılıklar mevcuttur.

Swagger içe aktarma yöntemleri

Swagger , API tanımlarını açıklamak için kullanılan bir belirtimdir. Arka uç uygulama hizmetlerinin API'lerini tanımlamak ve açıklamak amacıyla yaygın şekilde kullanılır. API Gateway, API'ler oluşturmak için bir Swagger 2.0 dosyasının içe aktarılmasını destekler. ImportSwagger işlemini çağırabilir veya bu işlemi konsolda yapabilirsiniz.

API Gateway konsolunun sol gezinme bölmesinde API Management > API List seçeneğini belirleyin. Ardından sayfanın sağ üst köşesindeki Import Swagger öğesine tıklayın.

Aşağıdaki bölümlerde API Gateway'in Swagger'a yönelik uzantıları açıklanmakta ve bu uzantıların nasıl kullanılacağını gösteren örnekler sunulmaktadır.

Önemli

Swagger'daki tüm parametreler ve değerler büyük/küçük harfe duyarlıdır.

Swagger uzantıları

API Gateway'in Swagger uzantıları, kimlik doğrulama, parametre eşleme ve arka uç hizmeti yetenekleri eklemek üzere Swagger'ın yerel Operation Object nesnesini genişletir. Herhangi bir HTTP yöntemini kullanan istekleri yakalamak için ANY yöntemi için de bir uzantı sağlanır. Tüm uzantılar x-aliyun-apigateway- ile başlar. Aşağıdaki bölümlerde her bir uzantı açıklanmaktadır.

Genel kapsam desteği

Aşağıdaki uzantılar genel kapsamda tanımlamaları destekler. Bir uzantı kendi kapsamında tanımlanmamışsa genel kapsamda tanımlanan değer otomatik olarak uygulanır. Uzantı kendi kapsamında tanımlanmışsa o kapsamdaki değer önceliklidir.

  • 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: Yetkilendirme türü

x-aliyun-apigateway-auth-type , Operation Object için geçerlidir ve API'nin yetkilendirme türünü belirtir.

Geçerli değerler:

  • APP (varsayılan): Alibaba Cloud API Gateway tarafından uygulama yetkilendirmesi.

  • ANONYMOUS: anonim erişim. Örnek:

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

x-aliyun-apigateway-api-market-enable: Alibaba Cloud Marketplace desteği

x-aliyun-apigateway-api-market-enable , Operation Object için geçerlidir ve API'nin Alibaba Cloud Marketplace'te yayımlanıp yayımlanamayacağını belirtir.

Geçerli değerler:

  • true

  • false (varsayılan) Örnek:

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

x-aliyun-apigateway-api-force-nonce-check: NONCE denetimi

x-aliyun-apigateway-api-force-nonce-check , Operation Object için geçerlidir ve API için bir NONCE denetiminin zorunlu olup olmadığını belirtir.

Geçerli değerler:

  • true

  • false (varsayılan) Örnek:

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

x-aliyun-apigateway-parameter-handling: Parametre eşleme

x-aliyun-apigateway-parameter-handling , Operation Object için geçerlidir ve istek parametrelerinin arka uç hizmeti parametrelerine nasıl eşleneceğini belirtir. Eşleme ilişkisi PASSTHROUGH olarak ayarlanırsa Parameter Object , x-aliyun-apigateway-backend-location ve x-aliyun-apigateway-backend-name özelliklerini desteklemez.

Geçerli değerler:

  • PASSTHROUGH (varsayılan): istek parametrelerini doğrudan iletir.

  • MAPPING: istek parametrelerini eşler. Örnek:

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

x-aliyun-apigateway-backend: Arka uç hizmeti türü

x-aliyun-apigateway-backend , Operation Object için geçerlidir ve arka uç hizmeti bilgilerini yapılandırır. Kullanılabilir özellikler aşağıdaki bölümlerde açıklandığı gibi arka uç hizmeti türüne bağlıdır.

Arka uç hizmeti türü: HTTP

Arka uç hizmetinin adresini doğrudan yapılandırmak için HTTP arka uç hizmeti türünü kullanın. Bu tür genellikle arka uç adresine doğrudan erişilebildiğinde kullanılır.

Aşağıdaki tabloda HTTP arka uç hizmeti türünün özellikleri açıklanmaktadır.

Özellik Tür Açıklama
type string Zorunludur. Değer HTTP olmalıdır.
address string Zorunludur. Arka uç hizmetinin adresini belirtir.
path string İsteğe bağlıdır. Arka uç hizmetinin yolunu belirtir. Yol değişkenleri desteklenir. Varsayılan olarak bu değer kök yolla aynıdır.
method string Zorunludur. Arka uç istek yöntemi.
timeout int İsteğe bağlıdır. Varsayılan değer: 10000. Geçerli değerler: 500 ila 30000.

Örnek:

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

Arka uç hizmeti türü: HTTP-VPC

Arka uç hizmeti bir VPC içinde bulunduğunda HTTP-VPC arka uç hizmeti türünü kullanın. Önce bir VPC yetkilendirmesi oluşturmanız ve ardından yetkilendirmeyi adına göre içe aktarmanız gerekir. Daha fazla bilgi için bkz. Arka uç hizmeti olarak VPC kaynağı kullanan bir API oluşturma.

Aşağıdaki tabloda HTTP-VPC arka uç hizmeti türünün özellikleri açıklanmaktadır.

Özellik Tür Açıklama
type string Zorunludur. Değer HTTP-VPC olmalıdır.
vpcAccessName string Zorunludur. Arka uç hizmetinin kullandığı VPC bağlantılı örneğin adı.
path string İsteğe bağlıdır. Arka uç hizmetinin yolunu belirtir. Yol değişkenleri desteklenir. Varsayılan olarak bu değer kök yolla aynıdır.
method string Zorunludur. Arka uç istek yöntemi.
timeout int İsteğe bağlıdır. Varsayılan değer: 10000. Geçerli değerler: 500 ila 30000.

Örnek:

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

Arka uç hizmeti türü: FC

API Gateway'in arka uç hizmeti Function Compute olduğunda FC arka uç hizmeti türünü kullanın.

Aşağıdaki tabloda FC arka uç hizmeti türünün özellikleri açıklanmaktadır.

Özellik Tür Açıklama
type string Zorunludur. Değer FC olmalıdır.
fcRegion string Zorunludur. Function Compute'un bulunduğu bölge.
serviceName string Zorunludur. Function Compute hizmetinin adı.
functionName string Zorunludur. Function Compute işlevinin adı.
arn string İsteğe bağlıdır. Function Compute için RAM yetkilendirmesi.

Örnek:

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

Arka uç hizmeti türü: MOCK

Önceden tanımladığınız yanıtı simüle etmek için MOCK arka uç hizmeti türünü kullanın.

Aşağıdaki tabloda MOCK arka uç hizmeti türünün özellikleri açıklanmaktadır.

Özellik Tür Açıklama
type string Zorunludur. Değer MOCK olmalıdır.
mockResult string Zorunludur. Simüle edilmiş yanıt.
mockStatusCode integer İsteğe bağlıdır.
mockHeaders Header İsteğe bağlıdır.

Aşağıdaki tabloda Header türünün özellikleri açıklanmaktadır.

Özellik Tür Açıklama
name string Zorunludur.
value string Zorunludur.

Örnek:

...
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: Sabit parametreler

x-aliyun-apigateway-constant-parameters , Operation Object için geçerlidir ve arka uç hizmetinin sabit parametrelerini tanımlar.

Aşağıdaki tabloda sabit bir parametrenin özellikleri açıklanmaktadır.

Özellik Tür Açıklama
backendName string Zorunludur. Arka uç parametresinin adı.
value string Zorunludur. Sabit değer.
location string Zorunludur. Sabit parametrenin depolandığı konum. Geçerli değerler: query ve header.
description string İsteğe bağlıdır. Sabiti açıklar.

Örnek:

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

x-aliyun-apigateway-system-parameters: Arka uç sistem parametreleri

x-aliyun-apigateway-system-parameters , Operation Object için geçerlidir ve API'nin arka uç hizmetinin sistem parametrelerini tanımlar.

Aşağıdaki tabloda bir arka uç sistem parametresinin özellikleri açıklanmaktadır.

Özellik Tür Açıklama
systemName string Zorunludur. Sistem parametresinin adı.
backendName string Zorunludur. Arka uç parametresinin adı.
location string Zorunludur. Sabit parametrenin depolandığı konum. Geçerli değerler: query ve header.

Örnek:

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

x-aliyun-apigateway-backend-location: Arka uç parametre konumu

x-aliyun-apigateway-backend-location , Parameter Object için geçerlidir ve parametre eşlemesinden sonra parametrenin arka uç hizmeti isteğindeki konumunu belirtir. Bu özellik yalnızca x-aliyun-apigateway-parameter-handling: MAPPING ayarlandığında etkili olur.

Geçerli değerler:

  • path

  • header

  • query

  • formData Örnek:

...
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: Arka uç parametre adı

x-aliyun-apigateway-backend-name , Parameter Object için geçerlidir ve parametre eşlemesinden sonra parametrenin arka uç hizmeti isteğindeki adını belirtir. Bu özellik yalnızca x-aliyun-apigateway-parameter-handling: MAPPING ayarlandığında etkili olur.

Örnek:

...
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: Sorgu parametresi şeması

x-aliyun-apigateway-query-schema , Parameter Object için geçerlidir ve bir sorgu parametresi için model tanımlar. Bir parametre String türündeyse ve sorgu parametresi olarak tanımlanmışsa bu uzantıyı kullanabilirsiniz.

Örnek:

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

x-aliyun-apigateway-any-method: ANY yöntemi

x-aliyun-apigateway-any-method , Path Item Object için geçerlidir ve API'nin herhangi bir türde HTTP isteği kabul etmesine olanak tanır.

Örnek:

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

x-aliyun-apigateway-app-code-type: AppCode kimlik doğrulaması

x-aliyun-apigateway-app-code-type , Operation Object için geçerlidir ve API'nin AppCode kimlik doğrulamasını destekleyip desteklemediğini belirtir.

Geçerli değerler:

  • DEFAULT (varsayılan)

  • DISABLE: AppCode kimlik doğrulamasını devre dışı bırakır.

  • HEADER: AppCode'u bir istek üstbilgisinde iletir.

  • HEADER_QUERY: AppCode'u bir istek üstbilgisinde veya sorgu parametresinde iletir. Örnek:

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

Swagger belirtiminden farklar

API Gateway ile Swagger belirtimi, API'leri tanımlarken aşağıdaki şekillerde farklılık gösterir. Bu farklılıklar Swagger içe aktarma özelliğini kullanma biçiminizi doğrudan etkiler.

Swagger parametre türleri ile özgün API Gateway türleri arasındaki eşleme

Swagger türü API Gateway türü Desteklenen doğrulama parametreleri ve kuralları
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 -

consumes alanı desteği

Bir Swagger yapılandırma dosyası formData parametreleri içeriyorsa consumes düğümünü yapılandırmanız gerekir. API Gateway şu anda yalnızca application/x-www-form-urlencoded türünü destekler.

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

Swagger tanımlarına ilişkin kısıtlamalar

Swagger içe aktarma, model tanımlarını destekler ancak uygulama özgün Swagger belirtiminden farklıdır. Model tanımları esas olarak yazılım geliştirme kitleri (SDK) oluşturmak için kullanılır. Bu nedenle özgün Swagger belirtimine ek olarak aşağıdaki kısıtlamalar getirilmiştir:

  • Swagger'daki schema etiketi yalnızca $ref türünü destekler.

  • Swagger definitions bölümündeki bir model yalnızca object türünde model tanımlarını destekler.

  • Swagger definitions bölümündeki bir model bir dizi tanımı içeriyorsa $ref başvurusu title etiketiyle birlikte kullanılmalıdır. Varsayılan olarak SDK oluşturma sırasında bir dizi türü ArrayList olarak oluşturulur.

Swagger örnekleri

Aşağıdaki örnekler, API Gateway'in Swagger uzantılarını kullanan eksiksiz Swagger tanımlarıdır. Kendi API'lerinizi tanımlarken bunları başlangıç noktası olarak kullanın.

Not

Örnekler yalnızca referans amaçlıdır.

Swagger örneği: HTTP arka uç hizmeti

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

Swagger örneği: HTTP-VPC arka uç hizmeti

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

Swagger örneği: Function Compute arka uç hizmeti

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

Swagger örneği: MOCK arka uç hizmeti

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