[Swagger-API] Fix operationIds in swagger description

[tlindener]

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]

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]

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