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.
API Gateway konsoluna giriş yapın.
Sol gezinme bölmesinde Manage APIs > APIs seçeneklerini belirleyin.
APIs sayfasında Import Swagger-compliant Data seçeneğine tıklayın.
-
Not iletişim kutusunda, Import Swagger-compliant Data sayfasına gitmek için Standard OAS seçeneğine tıklayın.
-
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.
ÖnemliAPI 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.
-
-
(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.
NotPass-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.
-
-
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:
ÖnemliHer yöntemle aynı anda en fazla 100 API tanımı içe aktarabilirsiniz.
Text: API tanımlarını YAML veya JSON formatında girin. API tanımlarının uzunluğu en fazla 256 KB olabilir.
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.
-
-
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. -
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.
NotUyarı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.
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.
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
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.
-
Swagger Object
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.
Schemes: API tanımındaki istek protokolleridir.
-
Path Item Object
Path: API tanımındaki istek yoludur.
Method: API tanımındaki istek yöntemidir. Geçerli değerler: GET, POST, PUT, HEAD, DELETE, PATCH ve OPTIONS.
-
Operation Object
Summary: API tanımının açıklamasıdır.
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.
Schemes: API tanımındaki istek protokolleridir. Operation Object içindeki Schemes, Swagger Object içindeki Schemes'e göre önceliklidir.
-
Parameter Object
Name: API tanımındaki istek parametresinin adıdır.
In: API tanımındaki istek parametresinin konumudur. Geçerli değerler: path, query, head ve formdata.
Description: API tanımındaki istek parametresinin açıklamasıdır.
Required: API tanımındaki istek parametresinin gerekli olup olmadığını belirtir.
-
Type: API tanımındaki istek parametresinin türüdür.
In değeri query, path veya head olarak ayarlandığında geçerli değerler: string, number, integer, boolean ve array.
In değeri formdata olarak ayarlandığında geçerli değerler: string, number, integer, boolean, array ve file.
-
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
FileNotBir 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.
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.
İ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.
-
Response Object
HTTP Status Code: API tanımında tanımlanan yanıtın hata kodu tanımında yer alan HTTP durum kodudur.
Description: API tanımındaki örnek yanıtta yer alan hata kodu tanımındaki açıklamadır.
Schema: API tanımında tanımlanan yanıtın hata kodu tanımında yer alan modeldir.
-
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.
-
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
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.
-
Path Item Object
Path: API tanımındaki istek yoludur.
Method: API tanımındaki istek yöntemidir. Geçerli değerler: GET, POST, PUT, HEAD, DELETE, PATCH ve OPTIONS.
-
Operation Object
Summary: API tanımının açıklamasıdır.
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.
-
Parameter Object
Name: API tanımındaki istek parametresinin adıdır.
In: API tanımındaki istek parametresinin konumudur. Geçerli değerler: path, query, head ve formdata.
Required: API tanımındaki istek parametresinin gerekli olup olmadığını belirtir.
-
Schema Object
Description: API tanımındaki istek parametresinin açıklamasıdır.
-
Type: API tanımındaki istek parametresinin türüdür.
In değeri query, path veya head olarak ayarlandığında geçerli değerler: string, number, integer, boolean ve array.
In değeri formdata olarak ayarlandığında geçerli değerler: string, number, integer, boolean, array ve file.
Format: API tanımındaki istek parametresinin formatıdır. Format, Type'a göre önceliklidir.
-
Request Body Object
-
Content
application/x-www-form-urlencoded: API tanımındaki formdata parametreleridir.
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.
-
-
Responses Object
HTTP Status Code: API tanımında tanımlanan yanıtın hata kodu tanımında yer alan HTTP durum kodudur.
Description: API tanımındaki örnek yanıtta yer alan hata kodu tanımındaki açıklamadır.
Content: API tanımında tanımlanan yanıtın hata kodu tanımındaki modeldir.
-
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.