search

amadeus-travel-innovation-sandbox / sandbox-content

Decommission of the Travel Innovation Sandbox
14 stars 28 forks source link

[Swagger-API] Fix operationIds in swagger description #6

Open tlindener opened 8 years ago

tlindener commented 8 years ago

Hi, the operationIds used in the swagger definition aren't working well with automated code generation. It would be great if you could provide an upgraded version where the ids don't have whitespaces.

tadhgpearson commented 7 years ago

Thanks for the feedback Thomas.

Our API catalog documentation is generated from this swagger file using Apigee Smartdocs. Today, Smartdocs uses the Operation ID to generate the page title and the left-hand navigation menu, so we have to format the operationID field in the way we want the page titles to be displayed on our site. Since the Smartdocs is closed source, we can't change that.

So I agree that the operation ID should be a programmable identifiers, and the summary should be used for the page title, as is now defined in the spec... but we're forced to work within the limitations of our tooling. I'll raise this issue to the Smartdocs team, and get back to you.

tlindener commented 7 years ago

Hi,

thank you for the feedback. I understand the problem although I would suggest to change it anyway. The "pain" caused by not so nice headlines is a lot less than the pain caused by the failures caused by wrong operationIds.

Best regards Tobias