[Rubocop] require api endpoint success response
Description of the proposal
- Ensures that all Grape API endpoints(endpoints defined in
desc
blocks) have a success response - The purpose of linting this param attribute is for the purposes of improving out OpenAPI documentation
- it is helpful for our api definitions to be consistent and param descriptions benefit api users
How to Validate these changes
Running the linter
- Open any grape entity file that is not listed in
.rubocop_todo/api/description_detail.yml
and remove thesuccess response
from any desc block - Run the new linter on that file ie
rubocop --only API/DescriptionSuccessResponse lib/api/badges.rb
- Observe the offense that was added
- Change the file back, run the linter again and see no offenses
Ensuring files with exceptions will be ignored
- run
rubocop --only API/DescriptionSuccessResponse --format files
- no files should be listed - Remove one of the files from
.rubocop_todo/api/description_success_response.yml
- run run
rubocop --only API/DescriptionSuccessResponse --format files
- see the file you removed listed
*** Add the file back to the exception list ***
Check-list
-
Make sure this MR enables a static analysis check rule for new usage but ignores current offenses. -
Mention this proposal in the relevant Slack channels (e.g. #development
,#backend
,#frontend
). -
If there is a choice to make between two potential styles, set up an emoji vote in the MR: - CHOICE_A:
🅰️ - CHOICE_B:
🅱️ - Vote for both choices, so they are visible to others.
- CHOICE_A:
-
The MR doesn't have significant objections, and is getting a majority of 👍 vs👎 (remember that we don't need to reach a consensus). -
(If applicable) One style is getting a majority of vote (compared to the other choice). -
(If applicable) Update the MR with the chosen style. -
Create a follow-up issue to fix the current offenses as a separate iteration: ISSUE_LINK -
Follow the review process as usual. -
Once approved and merged by a maintainer, mention it again: -
In the relevant Slack channels (e.g. #development
,#backend
,#frontend
). -
(Optional depending on the impact of the change) In the Engineering Week in Review.
-