i specify aws api gateway apis via open api spec. specs contain lot of documentation want client developers use when integrating apis. however, seems documentation add open api spec not exported api gateway , not available consumption.
as mentioned, start off open api spec in json. import api gateway using cloudformation aws::apigateway::restapi resource.
after deploy api stage and, finally, export documentation api+stage using aws cli:
aws apigateway get-export \ --parameters extensions='documentation' \ --rest-api-id abc123 \ --stage-name api \ --export-type swagger \ ./docs.json this export appears missing lot of crucial documentation properties such description , pattern.
an example open api parameter in api:
{ in: 'path', name: 'service', type: 'string', required: true, pattern: '^[-a-za-z0-9]+$', description: 'name of service (document) retrieve.' } when export aws-cli command above get:
{ "name" : "service", "in" : "path", "required" : true, "type" : "string" } the description , pattern properties have both been stripped documentation export bad since main part of documentation parameter.
also worth mentioning if export same api in aws console (swagger+api gateway extensions) same parameter definition did documentation export.
it might worth mentioning integrations based on lambda proxy if makes difference.
once swagger template imported, api gateway splits api definition , documentation in 2 separate entities. allows modify , deploy 2 independently.
the export feature exports whatever deployed stage. importing swagger template cause both api definition , documentation parts imported. however, looks deployed api definition. have explicitly publish documentation before becomes available in export.
like pointed out, can use cli publish new version of docs:
aws apigateway create-documentation-version \ --rest-api-id abc123 \ --documentation-version 1 \ --stage-name api
Comments
Post a Comment