cancel
Showing results for 
Search instead for 
Did you mean: 

Consistency request: Where should we put operationId?

SOLVED
Highlighted
Occasional Contributor

Consistency request: Where should we put operationId?

In an attempt to align ourselves I would like to propose we collectively decide on the location of operationId in an API def:

The SwaggerHub example found here: https://swagger.io/docs/specification/paths-and-operations/ has it located above the summary and description tags:

operationIDAtTop.PNG

but also beneath the description (my preference)

operationIDNotAtTop.PNG

 

How do you do it and can we agree on a standard so designers don't have to think / doubt on its location?

1 ACCEPTED SOLUTION

Accepted Solutions
Highlighted

Re: Consistency request: Where should we put operationId?

Hi @alex-savage 

Thanks for the question.  API standardization is one of the most important aspects of consistent API design and SwaggerHub has tools to help you do just that.  At SmartBear, we tend to put the OperationID right after the method name and have created a custom rule to enforce this in SwaggerHub.  You can view this rule and other in our public repo.

API Standardization: https://app.swaggerhub.com/help/organizations/api-standardization

GitHub Rules Library: https://github.com/SmartBear/swaggerhub-custom-rules-library

Feel free to try out these rule and tweak them as needed for your personal preference.

Hope this helps,

Tim

View solution in original post

2 REPLIES 2
Highlighted

Re: Consistency request: Where should we put operationId?

Hi @alex-savage 

Thanks for the question.  API standardization is one of the most important aspects of consistent API design and SwaggerHub has tools to help you do just that.  At SmartBear, we tend to put the OperationID right after the method name and have created a custom rule to enforce this in SwaggerHub.  You can view this rule and other in our public repo.

API Standardization: https://app.swaggerhub.com/help/organizations/api-standardization

GitHub Rules Library: https://github.com/SmartBear/swaggerhub-custom-rules-library

Feel free to try out these rule and tweak them as needed for your personal preference.

Hope this helps,

Tim

View solution in original post

Highlighted
Occasional Contributor

Re: Consistency request: Where should we put operationId?

New Here?
Join us and watch the welcome video:
Announcements