Duplicate operation descriptions in Open API definition

[xrysanthos]

There are many operations that have exactly the same description semantics even though they belong to different contexts. e.g.

• GET /contacts/
• GET /organizations/{organization_id}/contacts/
• GET /services/{service_id}/contacts/

all have the description Get Contacts.

Although this can be easily overlooked as it cannot be considered as a technical issue it really is a game changer when it comes to consumers that depend heavily on the semantics of the API.

I would be happy to assist with any metadata dedup / enrichment tasks.

[kinlane]

Thanks for pointing out. Known issue. With limited resources on staff, and this being a (mostly) unpaid role for myself, I have to pick my battles. I depend on the community to step in.

Feel free to edit the OpenAPI and submit pull requests for changes. My recommendation is that when you begin you drop a message here. To prevent any parallel work that is going on within the development from conflicting. Then when you submit pull request, it can be synced with dev efficiently.

Thanks for this.

[xrysanthos]

So, should I assume that the definition is crafted by hand and not auto-generated through code annotations? Just double-checking.

[kinlane]

It is the central truth. Not autogenerated. Managed on Github. All code, tests, docs, are generated from it. Correct.

[xrysanthos]

That's all I wanted to hear! Thanks Kin.

[xrysanthos]

@kinlane Just created a PR for this. Let me know if you need any clarifications.