Enhance API documentation and enforce linting standards #201
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Added Spectral Linter to the API project. This includes the necessary devDependencies and scripts in package.json, configuration in .spectral.yaml, and the required files in .gitignore. Issue: #200 Signed-off-by: Nikolay Martyanov <[email protected]>
Added a GitHub Actions workflow to automatically check API definitions with Spectral whenever a pull request is made to the main branch or it's updated/reopened. Also, the workflow will run whenever there's a push to the main branch. Issue: #200 Signed-off-by: Nikolay Martyanov <[email protected]>
Updated the cache keys in both `eslint-front.yml` and `eslint-back.yml` workflows. This change will help in differentiating the caches for frontend and backend. Signed-off-by: Nikolay Martyanov <[email protected]>
This commit adds server information to the api.yaml file. Both the local development server and production server URLs have been specified. Issue: #200 Signed-off-by: Nikolay Martyanov <[email protected]>
Updated the contact information: the name, url and email. Issue: #200 Signed-off-by: Nikolay Martyanov <[email protected]>
Updated the title of the API from "Region Tracking API" to "Track Your Regions API". Also added a description for the API. Issue: #200 Signed-off-by: Nikolay Martyanov <[email protected]>
Added detailed descriptions to the API endpoints for clarity and better understanding. This will help in effectively using the endpoints and knowing what to expect from them. Issue: #200 Signed-off-by: Nikolay Martyanov <[email protected]>
Assigned operationId for each endpoint for better identification of each API operation. This will help in generating better API documentation and client SDKs. Issue: #200 Signed-off-by: Nikolay Martyanov <[email protected]>
Added tags to categorize operations. This will make it easier to navigate and understand the structure of the API. Issue: #200 Signed-off-by: Nikolay Martyanov <[email protected]>
Updated the linting command in package.json to fail on warning severity level. This change will ensure stricter code quality checks. Issue: #200 Signed-off-by: Nikolay Martyanov <[email protected]>
Expanded and revised the README.md under the API directory. The revised document now includes more detailed guidelines, instructions for API linting using Spectral, and contribution procedures. Issue: #200 Signed-off-by: Nikolay Martyanov <[email protected]>
Closed
5 tasks
WalkthroughThe project has made several key changes to enhance the code quality and development workflow. Specifically, the GitHub Actions workflows for ESLint have been updated with more specific cache keys, and a new workflow for Spectral API checks has been introduced. Additionally, the API documentation and specification have undergone significant updates to improve clarity and include information on the API linting process. Changes
Assessment against linked issues
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? TipsChatThere are 3 ways to chat with CodeRabbit's AI:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (invoked as PR comments)
Additionally, you can add CodeRabbit Configration File (
|
Apply Sweep Rules to your PR?
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Review Status
Actionable comments generated: 1
Configuration used: .coderabbit.yaml
Files ignored due to filter (1)
- api/package.json
Files selected for processing (7)
- .github/workflows/eslint-back.yml (1 hunks)
- .github/workflows/eslint-front.yml (1 hunks)
- .github/workflows/spectral.yml (1 hunks)
- api/.gitignore (1 hunks)
- api/.spectral.yaml (1 hunks)
- api/README.md (1 hunks)
- api/api.yaml (9 hunks)
Files skipped from review due to trivial changes (3)
- .github/workflows/eslint-back.yml
- .github/workflows/eslint-front.yml
- api/.gitignore
Additional comments: 3
api/.spectral.yaml (1)
- 1-1: The extension of the default Spectral rules for OAS is noted and aligns with the PR's objectives.
api/README.md (1)
- 5-56: The updates to the
README.mdfile provide clear and detailed guidelines, structure information, and instructions for API linting with Spectral. These changes enhance the documentation and align with the PR's objectives.api/api.yaml (1)
- 1-29: > Note: This review was outside the patches, so it was mapped to the patch with the greatest overlap. Original lines [3-256]
The updates to the
api.yamlfile, including the new API title, contact information, server details, tags, and path descriptions, significantly improve the clarity and detail of the API specification. These changes are consistent with the OpenAPI Specification and the PR's objectives.
OhmSpectator
changed the title
There was a problem hiding this comment.
Review Status
Actionable comments generated: 0
Configuration used: .coderabbit.yaml
Files selected for processing (3)
- .github/workflows/eslint-back.yml (1 hunks)
- .github/workflows/eslint-front.yml (1 hunks)
- .github/workflows/spectral.yml (1 hunks)
Files skipped from review as they are similar to previous changes (1)
- .github/workflows/spectral.yml
Additional comments: 4
.github/workflows/eslint-back.yml (2)
47-47: The cache key has been correctly updated to include a "back-" prefix, ensuring differentiation of backend cache keys.
49-49: Ensure that the restore-keys pattern is consistent with the new cache key prefix.
.github/workflows/eslint-front.yml (2)
47-47: The cache key has been correctly updated to include a "front-" prefix, ensuring differentiation of frontend cache keys.
49-49: Ensure that the restore-keys pattern is consistent with the new cache key prefix.
Changed the GitHub Action's cache key from package-lock.json to package.json in eslint-front.yml, spectral.yml, and eslint-back.yml. The lock file does not exist yet at this moment. Issue: #200 Signed-off-by: Nikolay Martyanov <[email protected]>
OhmSpectator
force-pushed
the
feature/200-setup-api-linter
branch
from
8292b83 to
7a5b510
Compare
There was a problem hiding this comment.
Review Status
Actionable comments generated: 0
Configuration used: .coderabbit.yaml
Files selected for processing (3)
- .github/workflows/eslint-back.yml (1 hunks)
- .github/workflows/eslint-front.yml (1 hunks)
- .github/workflows/spectral.yml (1 hunks)
Files skipped from review as they are similar to previous changes (2)
- .github/workflows/eslint-front.yml
- .github/workflows/spectral.yml
Additional comments: 1
.github/workflows/eslint-back.yml (1)
- 47-47: The update to the cache key with the "back-" prefix is a good practice to differentiate between backend and frontend node modules cache.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
This PR introduces several enhancements to the API directory, focusing on implementing and enforcing standards through Spectral linting, updating API documentation, and improving the API definitions with proper details and organization. Key changes include setting up Spectral Linter, adding server information, updating contact and API information, adding endpoint descriptions, operation IDs, tags, and ensuring all linting warnings are treated as errors for stricter compliance.
Related Issues
Closes: #200
How Was This Tested?
Checklist
Before submitting your PR, please review the following:
Additional Comments (if any):
Summary by CodeRabbit
Chores
Documentation
New Features
Refactor