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.
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-backendx-aliyun-apigateway-api-market-enablex-aliyun-apigateway-api-force-nonce-checkx-aliyun-apigateway-parameter-handlingx-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:
truefalse(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:
truefalse(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:
pathheaderqueryformDataÖ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
schemaetiketi yalnızca$reftürünü destekler.Swagger
definitionsbölümündeki bir model yalnızca object türünde model tanımlarını destekler.Swagger
definitionsbölümündeki bir model bir dizi tanımı içeriyorsa$refbaşvurusutitleetiketiyle birlikte kullanılmalıdır. Varsayılan olarak SDK oluşturma sırasında bir dizi türüArrayListolarak 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.
Ö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