Migration de la documentation technique #2711
Conversation
|
Warning Rate limit exceeded@jonathanfallon has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 11 minutes and 53 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. WalkthroughThe changes in this pull request introduce a new GitHub pull request template to standardize the submission process for contributors. Additionally, modifications were made to deployment workflows by removing the "techdoc" project and adding a new workflow for deploying API documentation. Furthermore, new OpenAPI specifications for API versions 2.0, 3.0, and 3.1 were added, detailing various endpoints and their functionalities. Changes
Possibly related PRs
Suggested reviewers
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:
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 using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 14
🧹 Outside diff range and nitpick comments (15)
.github/workflows/deploy-techdoc.yaml (1)
14-25: Consider documentation versioning strategyThe matrix configuration reveals multiple API versions (v3.0, v3.1) being maintained simultaneously. This might benefit from:
- A clear versioning strategy for API documentation
- Automated version deprecation notices for older versions
- A migration guide between versions
Additionally, consider documenting why CEE documentation requires a separate deployment token.
.github/workflows/deploy-frontends-many.yml (1)
25-25: Add a comment to document the workflow splitConsider adding a comment to explain that techdoc deployment has been moved to a dedicated workflow.
+ # Note: API documentation deployment moved to deploy-techdoc.yml project_name: [attestation, dashboard]api/specs/cee-v3.0.yaml (4)
1-19: Clean up formatting issues.Remove trailing spaces on line 15 to maintain consistent formatting.
- description: Documentation générale + description: Documentation générale🧰 Tools
🪛 yamllint (1.35.1)
[error] 15-15: trailing spaces
(trailing-spaces)
🪛 checkov (3.2.312)
[HIGH] 1-495: Ensure that the global security field has rules defined
(CKV_OPENAPI_4)
119-123: Fix schema indentation.The
operator_journey_idschema has incorrect indentation (5 spaces instead of 6).- type: string - description: Identifiant du trajet envoyé par l'opérateur. Attention, cela correspond au `journey_id` de la version 2 de l'API. - pattern: /^[a-z0-9]{1,256}$/ - minLength: 1 - maxLength: 256 + type: string + description: Identifiant du trajet envoyé par l'opérateur. Attention, cela correspond au `journey_id` de la version 2 de l'API. + pattern: /^[a-z0-9]{1,256}$/ + minLength: 1 + maxLength: 256🧰 Tools
🪛 yamllint (1.35.1)
[warning] 119-119: wrong indentation: expected 6 but found 5
(indentation)
282-285: Consider using ISO 8601 format for consistency.The
datetimefield incee_applicationuses a number type. Consider using string with ISO 8601 format for consistency with other datetime fields in the API.datetime: - type: number + type: string + format: datetime description: Date de l'opération, en l'occurence date de fin du trajet pour la courte distance et date de paiement pour la longue.
304-304: Consider adding rate limit headers.The API documentation mentions a rate limit of 20,000 requests per minute. Consider adding standard rate limit headers (X-RateLimit-*) in the responses to help clients track their usage.
Also applies to: 362-362, 412-412, 438-438, 464-464
api/specs/api-v2.0.yaml (4)
33-35: Document migration plan for deprecated incentives properties.The comment indicates that
passenger.incentivesanddriver.incentivesare being deprecated in favor of a common property. Consider:
- Adding a specific version for the deprecation
- Documenting the migration steps
- Providing code examples for the new approach
🧰 Tools
🪛 yamllint (1.35.1)
[error] 33-33: trailing spaces
(trailing-spaces)
372-391: Enhance response examples for certificate creation.The success response could be improved by:
- Adding example values for all properties
- Including a complete response object
- Documenting rate limits if applicable
849-851: Clarify journey validation process.The description mentions a complex, asynchrone validation process but doesn't detail:
- The specific validation steps
- Expected processing times
- How to handle validation failures
1-1078: Fix YAML formatting issues.Multiple formatting issues were detected:
- Trailing spaces
- Inconsistent indentation
- Missing newline at end of file
Consider using a YAML formatter to automatically fix these issues.
🧰 Tools
🪛 yamllint (1.35.1)
[error] 15-15: trailing spaces
(trailing-spaces)
[error] 32-32: trailing spaces
(trailing-spaces)
[error] 33-33: trailing spaces
(trailing-spaces)
[error] 64-64: trailing spaces
(trailing-spaces)
[error] 72-72: trailing spaces
(trailing-spaces)
[error] 124-124: trailing spaces
(trailing-spaces)
[error] 149-149: trailing spaces
(trailing-spaces)
[error] 158-158: trailing spaces
(trailing-spaces)
[error] 196-196: trailing spaces
(trailing-spaces)
[error] 226-226: trailing spaces
(trailing-spaces)
[error] 231-231: trailing spaces
(trailing-spaces)
[warning] 295-295: wrong indentation: expected 8 but found 6
(indentation)
[error] 299-299: trailing spaces
(trailing-spaces)
[error] 301-301: trailing spaces
(trailing-spaces)
[error] 309-309: trailing spaces
(trailing-spaces)
[error] 311-311: trailing spaces
(trailing-spaces)
[error] 313-313: trailing spaces
(trailing-spaces)
[error] 315-315: trailing spaces
(trailing-spaces)
[error] 317-317: trailing spaces
(trailing-spaces)
[error] 319-319: trailing spaces
(trailing-spaces)
[error] 321-321: trailing spaces
(trailing-spaces)
[error] 425-425: trailing spaces
(trailing-spaces)
[warning] 442-442: wrong indentation: expected 8 but found 6
(indentation)
[error] 446-446: trailing spaces
(trailing-spaces)
[error] 448-448: trailing spaces
(trailing-spaces)
[error] 450-450: trailing spaces
(trailing-spaces)
[error] 453-453: trailing spaces
(trailing-spaces)
[error] 455-455: trailing spaces
(trailing-spaces)
[error] 457-457: trailing spaces
(trailing-spaces)
[error] 459-459: trailing spaces
(trailing-spaces)
[error] 461-461: trailing spaces
(trailing-spaces)
[error] 511-511: trailing spaces
(trailing-spaces)
[error] 514-514: trailing spaces
(trailing-spaces)
[error] 527-527: trailing spaces
(trailing-spaces)
[error] 535-535: trailing spaces
(trailing-spaces)
[error] 550-550: trailing spaces
(trailing-spaces)
[warning] 553-553: wrong indentation: expected 8 but found 6
(indentation)
[error] 569-569: trailing spaces
(trailing-spaces)
[error] 635-635: trailing spaces
(trailing-spaces)
[error] 643-643: trailing spaces
(trailing-spaces)
[warning] 652-652: wrong indentation: expected 8 but found 6
(indentation)
[error] 660-660: trailing spaces
(trailing-spaces)
[warning] 790-790: wrong indentation: expected 14 but found 15
(indentation)
[error] 824-824: trailing spaces
(trailing-spaces)
[error] 840-840: trailing spaces
(trailing-spaces)
[warning] 843-843: wrong indentation: expected 8 but found 6
(indentation)
[error] 856-856: trailing spaces
(trailing-spaces)
[error] 877-877: trailing spaces
(trailing-spaces)
[error] 893-893: trailing spaces
(trailing-spaces)
[error] 909-909: trailing spaces
(trailing-spaces)
[error] 917-917: trailing spaces
(trailing-spaces)
[warning] 925-925: wrong indentation: expected 8 but found 6
(indentation)
[error] 948-948: trailing spaces
(trailing-spaces)
[error] 956-956: trailing spaces
(trailing-spaces)
[warning] 965-965: wrong indentation: expected 8 but found 6
(indentation)
[error] 1078-1078: no new line character at the end of file
(new-line-at-end-of-file)
🪛 checkov (3.2.312)
[HIGH] 1-1079: Ensure that the global security field has rules defined
(CKV_OPENAPI_4)
api/specs/api-v3.0.yaml (2)
1-22: Consider adding additional OpenAPI metadata fields.The API metadata section could be enhanced by adding standard OpenAPI fields such as:
contactobject with structured contact informationtermsOfServiceURLserversarray for environment URLs instead of documenting them in the descriptionopenapi: '3.0.2' info: title: API Trajets version: "3.0" + contact: + name: Équipe technique + email: [email protected] + url: https://doc.covoiturage.beta.gouv.fr/ + termsOfService: https://doc.covoiturage.beta.gouv.fr/le-registre-de-preuve-de-covoiturage/kit-de-communication/cgu-conditions-generales-dutilisation description: | [Conditions Générales d'Utilisation](https://doc.covoiturage.beta.gouv.fr/le-registre-de-preuve-de-covoiturage/kit-de-communication/cgu-conditions-generales-dutilisation) | [Contact technique](mailto:[email protected]) | [Licence Apache-2.0](https://raw.githubusercontent.com/betagouv/preuve-covoiturage/main/LICENSE) | [Documentation Générale](https://doc.covoiturage.beta.gouv.fr/) - ### Environnements de l'API - - - production : [https://api.covoiturage.beta.gouv.fr/v3](https://api.covoiturage.beta.gouv.fr/v3) - - demo : [https://api.demo.covoiturage.beta.gouv.fr/v3](https://api.demo.covoiturage.beta.gouv.fr/v3) + servers: + - url: https://api.covoiturage.beta.gouv.fr/v3 + description: Production + - url: https://api.demo.covoiturage.beta.gouv.fr/v3 + description: Demo🧰 Tools
🪛 checkov (3.2.312)
[HIGH] 1-1455: Ensure that the global security field has rules defined
(CKV_OPENAPI_4)
[HIGH] 1-1455: Ensure that security operations is not empty.
(CKV_OPENAPI_5)
503-892: Fix inconsistent tag indentation in path operations.Several operations have inconsistent indentation in their tags section.
/journeys: post: tags: - - Trajets + - Trajets summary: Envoyer un trajet🧰 Tools
🪛 yamllint (1.35.1)
[warning] 507-507: wrong indentation: expected 8 but found 6
(indentation)
[warning] 591-591: wrong indentation: expected 14 but found 15
(indentation)
[warning] 636-636: wrong indentation: expected 8 but found 6
(indentation)
[warning] 698-698: wrong indentation: expected 8 but found 6
(indentation)
[error] 759-759: trailing spaces
(trailing-spaces)
[warning] 789-789: wrong indentation: expected 8 but found 6
(indentation)
[warning] 836-836: wrong indentation: expected 8 but found 6
(indentation)
api/specs/api-v3.1.yaml (3)
356-384: Fix indentation in driving_license schemaThe indentation is inconsistent with the rest of the file, which affects readability.
Apply this indentation fix:
- driving_license: - description: | + driving_license: + description: |🧰 Tools
🪛 yamllint (1.35.1)
[warning] 356-356: wrong indentation: expected 10 but found 12
(indentation)
504-544: Add rate limiting headers to journey creation endpointWhile the rate limiting is mentioned in the description, it should be reflected in the API response headers.
Add the following response headers to the 201 response:
responses: '201': description: OK. Le trajet a bien été enregistré. + headers: + X-RateLimit-Limit: + description: The number of allowed requests in the current period + schema: + type: integer + X-RateLimit-Remaining: + description: The number of remaining requests in the current period + schema: + type: integer🧰 Tools
🪛 yamllint (1.35.1)
[warning] 507-507: wrong indentation: expected 8 but found 6
(indentation)
1027-1036: Remove trailing spaces in documentationThere are trailing spaces in the documentation that should be removed to maintain consistent formatting.
Remove trailing spaces from the following lines:
- Line 1027:
tags:- Line 1036:
Les exports sont conservés 7 jours.- Line 1052:
tz:- Line 1123: Empty line with spaces
Also applies to: 1052-1052, 1123-1123
🧰 Tools
🪛 yamllint (1.35.1)
[error] 1027-1027: trailing spaces
(trailing-spaces)
[error] 1036-1036: trailing spaces
(trailing-spaces)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (7)
.github/pull_request_template.md(1 hunks).github/workflows/deploy-frontends-many.yml(1 hunks).github/workflows/deploy-techdoc.yaml(1 hunks)api/specs/api-v2.0.yaml(1 hunks)api/specs/api-v3.0.yaml(1 hunks)api/specs/api-v3.1.yaml(1 hunks)api/specs/cee-v3.0.yaml(1 hunks)
🧰 Additional context used
🪛 Markdownlint (0.35.0)
.github/pull_request_template.md
30-30: Expected: 0; Actual: 1
Unordered list indentation
(MD007, ul-indent)
31-31: Expected: 0; Actual: 1
Unordered list indentation
(MD007, ul-indent)
32-32: Expected: 0; Actual: 1
Unordered list indentation
(MD007, ul-indent)
33-33: Expected: 0; Actual: 1
Unordered list indentation
(MD007, ul-indent)
34-34: Expected: 0; Actual: 1
Unordered list indentation
(MD007, ul-indent)
35-35: Expected: 0; Actual: 1
Unordered list indentation
(MD007, ul-indent)
36-36: Expected: 0; Actual: 1
Unordered list indentation
(MD007, ul-indent)
37-37: Expected: 0; Actual: 1
Unordered list indentation
(MD007, ul-indent)
1-1: null
No space after hash on atx style heading
(MD018, no-missing-space-atx)
19-19: null
Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🪛 yamllint (1.35.1)
api/specs/api-v2.0.yaml
[error] 15-15: trailing spaces
(trailing-spaces)
[error] 32-32: trailing spaces
(trailing-spaces)
[error] 33-33: trailing spaces
(trailing-spaces)
[error] 64-64: trailing spaces
(trailing-spaces)
[error] 72-72: trailing spaces
(trailing-spaces)
[error] 124-124: trailing spaces
(trailing-spaces)
[error] 149-149: trailing spaces
(trailing-spaces)
[error] 158-158: trailing spaces
(trailing-spaces)
[error] 196-196: trailing spaces
(trailing-spaces)
[error] 226-226: trailing spaces
(trailing-spaces)
[error] 231-231: trailing spaces
(trailing-spaces)
[warning] 295-295: wrong indentation: expected 8 but found 6
(indentation)
[error] 299-299: trailing spaces
(trailing-spaces)
[error] 301-301: trailing spaces
(trailing-spaces)
[error] 309-309: trailing spaces
(trailing-spaces)
[error] 311-311: trailing spaces
(trailing-spaces)
[error] 313-313: trailing spaces
(trailing-spaces)
[error] 315-315: trailing spaces
(trailing-spaces)
[error] 317-317: trailing spaces
(trailing-spaces)
[error] 319-319: trailing spaces
(trailing-spaces)
[error] 321-321: trailing spaces
(trailing-spaces)
[error] 425-425: trailing spaces
(trailing-spaces)
[warning] 442-442: wrong indentation: expected 8 but found 6
(indentation)
[error] 446-446: trailing spaces
(trailing-spaces)
[error] 448-448: trailing spaces
(trailing-spaces)
[error] 450-450: trailing spaces
(trailing-spaces)
[error] 453-453: trailing spaces
(trailing-spaces)
[error] 455-455: trailing spaces
(trailing-spaces)
[error] 457-457: trailing spaces
(trailing-spaces)
[error] 459-459: trailing spaces
(trailing-spaces)
[error] 461-461: trailing spaces
(trailing-spaces)
[error] 511-511: trailing spaces
(trailing-spaces)
[error] 514-514: trailing spaces
(trailing-spaces)
[error] 527-527: trailing spaces
(trailing-spaces)
[error] 535-535: trailing spaces
(trailing-spaces)
[error] 550-550: trailing spaces
(trailing-spaces)
[warning] 553-553: wrong indentation: expected 8 but found 6
(indentation)
[error] 569-569: trailing spaces
(trailing-spaces)
[error] 635-635: trailing spaces
(trailing-spaces)
[error] 643-643: trailing spaces
(trailing-spaces)
[warning] 652-652: wrong indentation: expected 8 but found 6
(indentation)
[error] 660-660: trailing spaces
(trailing-spaces)
[warning] 790-790: wrong indentation: expected 14 but found 15
(indentation)
[error] 824-824: trailing spaces
(trailing-spaces)
[error] 840-840: trailing spaces
(trailing-spaces)
[warning] 843-843: wrong indentation: expected 8 but found 6
(indentation)
[error] 856-856: trailing spaces
(trailing-spaces)
[error] 877-877: trailing spaces
(trailing-spaces)
[error] 893-893: trailing spaces
(trailing-spaces)
[error] 909-909: trailing spaces
(trailing-spaces)
[error] 917-917: trailing spaces
(trailing-spaces)
[warning] 925-925: wrong indentation: expected 8 but found 6
(indentation)
[error] 948-948: trailing spaces
(trailing-spaces)
[error] 956-956: trailing spaces
(trailing-spaces)
[warning] 965-965: wrong indentation: expected 8 but found 6
(indentation)
[error] 1078-1078: no new line character at the end of file
(new-line-at-end-of-file)
api/specs/api-v3.0.yaml
[warning] 356-356: wrong indentation: expected 10 but found 12
(indentation)
[warning] 507-507: wrong indentation: expected 8 but found 6
(indentation)
[warning] 591-591: wrong indentation: expected 14 but found 15
(indentation)
[warning] 636-636: wrong indentation: expected 8 but found 6
(indentation)
[warning] 698-698: wrong indentation: expected 8 but found 6
(indentation)
[error] 759-759: trailing spaces
(trailing-spaces)
[warning] 789-789: wrong indentation: expected 8 but found 6
(indentation)
[warning] 836-836: wrong indentation: expected 8 but found 6
(indentation)
[warning] 943-943: wrong indentation: expected 8 but found 6
(indentation)
[warning] 976-976: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1005-1005: wrong indentation: expected 8 but found 6
(indentation)
[error] 1027-1027: trailing spaces
(trailing-spaces)
[error] 1036-1036: trailing spaces
(trailing-spaces)
[error] 1052-1052: trailing spaces
(trailing-spaces)
[error] 1123-1123: trailing spaces
(trailing-spaces)
[warning] 1127-1127: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1263-1263: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1368-1368: wrong indentation: expected 8 but found 6
(indentation)
api/specs/api-v3.1.yaml
[warning] 356-356: wrong indentation: expected 10 but found 12
(indentation)
[warning] 507-507: wrong indentation: expected 8 but found 6
(indentation)
[warning] 591-591: wrong indentation: expected 14 but found 15
(indentation)
[warning] 636-636: wrong indentation: expected 8 but found 6
(indentation)
[warning] 698-698: wrong indentation: expected 8 but found 6
(indentation)
[error] 759-759: trailing spaces
(trailing-spaces)
[warning] 789-789: wrong indentation: expected 8 but found 6
(indentation)
[warning] 836-836: wrong indentation: expected 8 but found 6
(indentation)
[warning] 943-943: wrong indentation: expected 8 but found 6
(indentation)
[warning] 976-976: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1005-1005: wrong indentation: expected 8 but found 6
(indentation)
[error] 1027-1027: trailing spaces
(trailing-spaces)
[error] 1036-1036: trailing spaces
(trailing-spaces)
[error] 1052-1052: trailing spaces
(trailing-spaces)
[error] 1123-1123: trailing spaces
(trailing-spaces)
[warning] 1127-1127: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1263-1263: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1368-1368: wrong indentation: expected 8 but found 6
(indentation)
api/specs/cee-v3.0.yaml
[error] 15-15: trailing spaces
(trailing-spaces)
[error] 45-45: trailing spaces
(trailing-spaces)
[warning] 119-119: wrong indentation: expected 6 but found 5
(indentation)
[warning] 172-172: wrong indentation: expected 12 but found 10
(indentation)
[warning] 176-176: wrong indentation: expected 12 but found 10
(indentation)
[error] 226-226: trailing spaces
(trailing-spaces)
[error] 258-258: trailing spaces
(trailing-spaces)
[warning] 301-301: wrong indentation: expected 8 but found 6
(indentation)
[error] 336-336: trailing spaces
(trailing-spaces)
[warning] 359-359: wrong indentation: expected 8 but found 6
(indentation)
[warning] 409-409: wrong indentation: expected 8 but found 6
(indentation)
[warning] 435-435: wrong indentation: expected 8 but found 6
(indentation)
[warning] 461-461: wrong indentation: expected 8 but found 6
(indentation)
[warning] 481-481: wrong indentation: expected 8 but found 6
(indentation)
[error] 494-494: no new line character at the end of file
(new-line-at-end-of-file)
🪛 checkov (3.2.312)
api/specs/api-v2.0.yaml
[HIGH] 1-1079: Ensure that the global security field has rules defined
(CKV_OPENAPI_4)
api/specs/api-v3.0.yaml
[HIGH] 1-1455: Ensure that the global security field has rules defined
(CKV_OPENAPI_4)
[HIGH] 1-1455: Ensure that security operations is not empty.
(CKV_OPENAPI_5)
api/specs/api-v3.1.yaml
[HIGH] 1-1455: Ensure that the global security field has rules defined
(CKV_OPENAPI_4)
[HIGH] 1-1455: Ensure that security operations is not empty.
(CKV_OPENAPI_5)
api/specs/cee-v3.0.yaml
[HIGH] 1-495: Ensure that the global security field has rules defined
(CKV_OPENAPI_4)
🔇 Additional comments (3)
.github/workflows/deploy-frontends-many.yml (1)
25-25: LGTM! Verify documentation deployment migration
The removal of 'techdoc' from the deployment matrix aligns with the documentation migration strategy.
Let's verify the migration is complete:
✅ Verification successful
Migration verified: techdoc deployment successfully moved to bump.sh
The removal of 'techdoc' from the deployment matrix is correct as the technical documentation deployment has been properly migrated to a new workflow (deploy-techdoc.yaml) that uses bump.sh for API documentation hosting. The new workflow:
- Handles API documentation deployment for multiple versions (v3.0, v3.1)
- Uses bump.sh GitHub action for deployment
- No residual S3 bucket or old techdoc deployment references found
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash
# Description: Verify the new techdoc workflow exists and no references to old deployment remain
# Check if the new workflow file exists
echo "Checking for new techdoc workflow..."
fd "deploy-techdoc.ya?ml" .github/workflows/
# Check for any remaining references to techdoc deployment
echo "Checking for remaining techdoc deployment references..."
rg -i "techdoc.*bucket" .github/
Length of output: 323
Script:
#!/bin/bash
# Let's verify the content of the new workflow and any remaining techdoc references
# Check the content of the new techdoc workflow
echo "Content of deploy-techdoc.yaml:"
cat .github/workflows/deploy-techdoc.yaml
# Search for any techdoc references in workflows
echo -e "\nChecking for techdoc references in workflows:"
rg -i "techdoc" .github/workflows/ -A 2 -B 2
# Search for any S3 bucket or deployment references that might be related
echo -e "\nChecking for S3/deployment references:"
rg -i "(bucket|deploy).*techdoc|techdoc.*(bucket|deploy)" .github/
Length of output: 1300
api/specs/api-v2.0.yaml (1)
1-20: LGTM: API metadata is well-structured and complete.
The metadata section provides comprehensive information including version, title, terms of service, contact details, and server URLs for both production and demo environments.
🧰 Tools
🪛 yamllint (1.35.1)
[error] 15-15: trailing spaces
(trailing-spaces)
🪛 checkov (3.2.312)
[HIGH] 1-1079: Ensure that the global security field has rules defined
(CKV_OPENAPI_4)
api/specs/api-v3.1.yaml (1)
1-1453: Overall, the API specification is well-designed and production-ready
The specification demonstrates:
- Comprehensive schema validation
- Proper error handling
- Detailed documentation
- Clear authentication mechanisms
The suggested improvements are minor and don't affect the core functionality.
🧰 Tools
🪛 yamllint (1.35.1)
[warning] 356-356: wrong indentation: expected 10 but found 12
(indentation)
[warning] 507-507: wrong indentation: expected 8 but found 6
(indentation)
[warning] 591-591: wrong indentation: expected 14 but found 15
(indentation)
[warning] 636-636: wrong indentation: expected 8 but found 6
(indentation)
[warning] 698-698: wrong indentation: expected 8 but found 6
(indentation)
[error] 759-759: trailing spaces
(trailing-spaces)
[warning] 789-789: wrong indentation: expected 8 but found 6
(indentation)
[warning] 836-836: wrong indentation: expected 8 but found 6
(indentation)
[warning] 943-943: wrong indentation: expected 8 but found 6
(indentation)
[warning] 976-976: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1005-1005: wrong indentation: expected 8 but found 6
(indentation)
[error] 1027-1027: trailing spaces
(trailing-spaces)
[error] 1036-1036: trailing spaces
(trailing-spaces)
[error] 1052-1052: trailing spaces
(trailing-spaces)
[error] 1123-1123: trailing spaces
(trailing-spaces)
[warning] 1127-1127: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1263-1263: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1368-1368: wrong indentation: expected 8 but found 6
(indentation)
🪛 checkov (3.2.312)
[HIGH] 1-1455: Ensure that the global security field has rules defined
(CKV_OPENAPI_4)
[HIGH] 1-1455: Ensure that security operations is not empty.
(CKV_OPENAPI_5)
api/specs/cee-v3.0.yaml
Outdated
| get: | ||
| tags: | ||
| - cee | ||
| summary: Chercher une demande CEE | ||
| description: | | ||
| L'API peut être utilisée jusqu'à 20.000x par minute. | ||
| security: | ||
| - token: [] | ||
| operationId: policy:cee:find | ||
| responses: | ||
| '200': | ||
| description: La demande a été trouvée et appartient à l'opérateur. | ||
| content: | ||
| 'application/json': | ||
| schema: | ||
| '$ref': '#/components/schemas/cee_application' | ||
| '404': | ||
| description: La demande n'a pas été trouvée | ||
| '403': | ||
| description: La demande ne peut aboutir car celle-ci appartient à un autre opérateur | ||
| delete: | ||
| tags: | ||
| - cee | ||
| summary: Supprimer une demande CEE | ||
| description: | | ||
| L'API peut être utilisée jusqu'à 20.000x par minute. | ||
| security: | ||
| - token: [] | ||
| operationId: policy:cee:delete | ||
| responses: | ||
| '204': | ||
| description: La demande a été trouvée et a bien été supprimée. | ||
| '404': | ||
| description: La demande n'a pas été trouvée. | ||
| '403': | ||
| description: La demande ne peut aboutir car celle-ci appartient à un autre opérateur. |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Add path parameters documentation.
The /policies/cee/{uuid} endpoints are missing parameter documentation for the uuid path parameter.
Add the following under the get and delete operations:
parameters:
- name: uuid
in: path
required: true
schema:
$ref: '#/components/schemas/cee_application_uuid'
description: UUID of the CEE application to retrieve or delete🧰 Tools
🪛 yamllint (1.35.1)
[warning] 461-461: wrong indentation: expected 8 but found 6
(indentation)
[warning] 481-481: wrong indentation: expected 8 but found 6
(indentation)
[error] 494-494: no new line character at the end of file
(new-line-at-end-of-file)
|
@jonathanfallon Quand je run la doc en local, j'ai pas la 3.1 qui s'affiche. J'ai comme la version de prod 🤔 |
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Outside diff range and nitpick comments (3)
.github/workflows/deploy-techdoc.yaml (1)
31-42: Enhance OpenAPI validationThe current validation is basic. Consider adding more comprehensive checks:
- Schema validation
- Security requirements validation
- Response validation
Add these additional validation steps:
- name: Validate OpenAPI syntax uses: swagger-api/validator-action@v1 with: files: api/specs/${{ matrix.doc }}-${{ matrix.version }}.yaml + - name: Additional OpenAPI validations + run: | + npx @stoplight/spectral-cli lint api/specs/${{ matrix.doc }}-${{ matrix.version }}.yaml \ + --ruleset https://raw.githubusercontent.com/stoplightio/spectral/master/rulesets/oas/index.jsonapi/specs/api-v3.1.yaml (2)
15-16: Document rate limits consistentlyThe rate limiting information is mentioned in the description but should be consistently documented across all endpoints. Currently, it only mentions "20000 requests per minute" for journey submissions.
Consider adding a standardized rate limit section in the description of each endpoint or as a global note. For example:
### Précisions d'usage - Attention, l'API v3.1 nécessite d'envoyer des preuves au plus tard 24h après le début du trajet. - - Un _rate limiting_ de 20000 requêtes par minute est appliqué sur l'envoi des trajets. Les différents points d'API ont des _rate limiters_ indépendants. + ### Rate Limiting + - Trajets: 20000 requêtes par minute + - Géographie: 20000 requêtes par minute + - Attestations: 20000 requêtes par minute + - CEE: 20000 requêtes par minute
589-600: Clarify anomaly detection thresholdsThe anomaly detection rules use magic numbers without clear justification:
- 2.5x for time/distance ratio
- 4x for distance comparison
- 7x for duration comparison
Consider:
- Document the reasoning behind these thresholds
- Make them configurable parameters
- Add examples of real-world scenarios that trigger these thresholds
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (2)
.github/workflows/deploy-techdoc.yaml(1 hunks)api/specs/api-v3.1.yaml(1 hunks)
🧰 Additional context used
🪛 yamllint (1.35.1)
api/specs/api-v3.1.yaml
[error] 33-33: trailing spaces
(trailing-spaces)
[error] 329-329: trailing spaces
(trailing-spaces)
[error] 390-390: trailing spaces
(trailing-spaces)
[warning] 396-396: wrong indentation: expected 6 but found 8
(indentation)
[error] 444-444: trailing spaces
(trailing-spaces)
[warning] 631-631: wrong indentation: expected 12 but found 10
(indentation)
[warning] 635-635: wrong indentation: expected 12 but found 10
(indentation)
[error] 685-685: trailing spaces
(trailing-spaces)
[error] 717-717: trailing spaces
(trailing-spaces)
[warning] 762-762: wrong indentation: expected 8 but found 6
(indentation)
[warning] 846-846: wrong indentation: expected 14 but found 15
(indentation)
[warning] 891-891: wrong indentation: expected 8 but found 6
(indentation)
[warning] 953-953: wrong indentation: expected 8 but found 6
(indentation)
[error] 1014-1014: trailing spaces
(trailing-spaces)
[warning] 1044-1044: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1091-1091: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1198-1198: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1231-1231: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1260-1260: wrong indentation: expected 8 but found 6
(indentation)
[error] 1282-1282: trailing spaces
(trailing-spaces)
[error] 1291-1291: trailing spaces
(trailing-spaces)
[error] 1307-1307: trailing spaces
(trailing-spaces)
[error] 1378-1378: trailing spaces
(trailing-spaces)
[warning] 1382-1382: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1518-1518: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1623-1623: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1713-1713: wrong indentation: expected 8 but found 6
(indentation)
[error] 1748-1748: trailing spaces
(trailing-spaces)
[warning] 1771-1771: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1821-1821: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1847-1847: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1873-1873: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1900-1900: wrong indentation: expected 8 but found 6
(indentation)
[error] 1913-1913: trailing spaces
(trailing-spaces)
🔇 Additional comments (3)
.github/workflows/deploy-techdoc.yaml (1)
17-26:
Missing CEE v3.1 specification in matrix
The matrix includes API v3.0, v3.1, and CEE v3.0, but CEE v3.1 is missing. This seems inconsistent with the versioning pattern.
api/specs/api-v3.1.yaml (2)
24-25: Security scheme is correctly configured
The global security requirement is properly set up to require bearer token authentication for all endpoints.
119-121: Review operator_journey_id pattern
The pattern for operator_journey_id seems too restrictive:
- Only allows lowercase letters and numbers
- Maximum length of 256 characters might be too long for efficient indexing
Consider:
- Adding uppercase letters to support existing IDs
- Reducing max length to 128 characters for better index performance
- Adding a minimum length requirement
There was a problem hiding this comment.
Actionable comments posted: 5
🧹 Outside diff range and nitpick comments (3)
.github/workflows/deploy-techdoc.yaml (1)
41-47: Add error handling for deployment stepThe deployment step should handle potential failures gracefully.
- name: Deploy uses: bump-sh/github-action@v1 + id: deploy with: doc: ${{ matrix.doc }} token: ${{ secrets[matrix.token] }} file: api/specs/${{ matrix.doc }}-${{ matrix.version }}.yaml branch: ${{ matrix.version }} + continue-on-error: true + + - name: Report deployment failure + if: steps.deploy.outcome == 'failure' + run: | + echo "::error::Failed to deploy ${{ matrix.doc }}-${{ matrix.version }}.yaml" + exit 1api/specs/api-v3.1.yaml (2)
634-644: Fix indentation in oneOf required fieldsThe indentation of required fields in the oneOf schema is incorrect.
oneOf: - required: - - Demandes CEE_application_type - - Demandes CEE_application_uuid - - identity_key + - cee_application_type + - cee_application_uuid + - identity_key - required: - - Demandes CEE_application_type - - identity_key - - phone_trunc - - last_name_trunc - - journey_type - - datetime + - cee_application_type + - identity_key + - phone_trunc + - last_name_trunc + - journey_type + - datetime🧰 Tools
🪛 yamllint (1.35.1)
[warning] 634-634: wrong indentation: expected 12 but found 10
(indentation)
[warning] 638-638: wrong indentation: expected 12 but found 10
(indentation)
765-1910: Fix tag indentation in pathsMultiple tags in path operations have incorrect indentation.
post: tags: - - Trajets courte distance + - Trajets courte distanceApply similar fixes to all tag indentations in the paths section.
🧰 Tools
🪛 yamllint (1.35.1)
[warning] 765-765: wrong indentation: expected 8 but found 6
(indentation)
[error] 792-792: trailing spaces
(trailing-spaces)
[warning] 855-855: wrong indentation: expected 14 but found 15
(indentation)
[warning] 900-900: wrong indentation: expected 8 but found 6
(indentation)
[warning] 962-962: wrong indentation: expected 8 but found 6
(indentation)
[error] 1022-1022: trailing spaces
(trailing-spaces)
[warning] 1052-1052: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1098-1098: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1203-1203: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1235-1235: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1263-1263: wrong indentation: expected 8 but found 6
(indentation)
[error] 1284-1284: trailing spaces
(trailing-spaces)
[error] 1292-1292: trailing spaces
(trailing-spaces)
[error] 1308-1308: trailing spaces
(trailing-spaces)
[error] 1379-1379: trailing spaces
(trailing-spaces)
[warning] 1383-1383: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1516-1516: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1620-1620: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1709-1709: wrong indentation: expected 8 but found 6
(indentation)
[error] 1743-1743: trailing spaces
(trailing-spaces)
[warning] 1766-1766: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1815-1815: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1840-1840: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1865-1865: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1891-1891: wrong indentation: expected 8 but found 6
(indentation)
[error] 1903-1903: trailing spaces
(trailing-spaces)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (2)
.github/workflows/deploy-techdoc.yaml(1 hunks)api/specs/api-v3.1.yaml(1 hunks)
🧰 Additional context used
🪛 yamllint (1.35.1)
api/specs/api-v3.1.yaml
[error] 17-17: trailing spaces
(trailing-spaces)
[error] 36-36: trailing spaces
(trailing-spaces)
[error] 332-332: trailing spaces
(trailing-spaces)
[error] 393-393: trailing spaces
(trailing-spaces)
[warning] 399-399: wrong indentation: expected 6 but found 8
(indentation)
[error] 447-447: trailing spaces
(trailing-spaces)
[warning] 634-634: wrong indentation: expected 12 but found 10
(indentation)
[warning] 638-638: wrong indentation: expected 12 but found 10
(indentation)
[error] 688-688: trailing spaces
(trailing-spaces)
[error] 720-720: trailing spaces
(trailing-spaces)
[warning] 765-765: wrong indentation: expected 8 but found 6
(indentation)
[error] 792-792: trailing spaces
(trailing-spaces)
[warning] 855-855: wrong indentation: expected 14 but found 15
(indentation)
[warning] 900-900: wrong indentation: expected 8 but found 6
(indentation)
[warning] 962-962: wrong indentation: expected 8 but found 6
(indentation)
[error] 1022-1022: trailing spaces
(trailing-spaces)
[warning] 1052-1052: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1098-1098: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1203-1203: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1235-1235: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1263-1263: wrong indentation: expected 8 but found 6
(indentation)
[error] 1284-1284: trailing spaces
(trailing-spaces)
[error] 1292-1292: trailing spaces
(trailing-spaces)
[error] 1308-1308: trailing spaces
(trailing-spaces)
[error] 1379-1379: trailing spaces
(trailing-spaces)
[warning] 1383-1383: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1516-1516: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1620-1620: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1709-1709: wrong indentation: expected 8 but found 6
(indentation)
[error] 1743-1743: trailing spaces
(trailing-spaces)
[warning] 1766-1766: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1815-1815: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1840-1840: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1865-1865: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1891-1891: wrong indentation: expected 8 but found 6
(indentation)
[error] 1903-1903: trailing spaces
(trailing-spaces)
.github/workflows/deploy-techdoc.yaml
[error] 12-12: trailing spaces
(trailing-spaces)
🔇 Additional comments (4)
.github/workflows/deploy-techdoc.yaml (2)
28-40: LGTM: Validation steps are well implemented
The validation steps correctly:
- Verify file existence
- Validate OpenAPI syntax
14-23:
Add missing CEE v3.1 specification to matrix
The matrix includes API v3.0 and v3.1 but omits CEE v3.1. This is inconsistent with the available specifications.
strategy:
matrix:
include:
- doc: api
version: v3.1
token: BUMP_TOKEN_API
- doc: api
version: v3.0
token: BUMP_TOKEN_API
+ - doc: cee
+ version: v3.1
+ token: BUMP_TOKEN_CEELikely invalid or redundant comment.
api/specs/api-v3.1.yaml (2)
1-25: LGTM: API metadata is well documented
The API metadata section includes all essential information:
- Version and title
- Terms of service link
- Contact information
- License details
- Clear description in French
- Production and pre-production servers
🧰 Tools
🪛 yamllint (1.35.1)
[error] 17-17: trailing spaces
(trailing-spaces)
27-35: LGTM: Security scheme is properly configured
The global security requirement and bearer token authentication are correctly configured.
| name: Deploy API documentation | ||
| permissions: | ||
| contents: read | ||
| on: | ||
| workflow_dispatch: | ||
| release: | ||
| types: [published] | ||
| jobs: |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Add missing workflow triggers
The workflow is only triggered by workflow_dispatch and release events. Consider adding:
pushevents for automated deployments when documentation changespull_requestevents for validation on PRs
name: Deploy API documentation
permissions:
contents: read
on:
workflow_dispatch:
release:
types: [published]
+ push:
+ paths:
+ - 'api/specs/**'
+ pull_request:
+ paths:
+ - 'api/specs/**'📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| name: Deploy API documentation | |
| permissions: | |
| contents: read | |
| on: | |
| workflow_dispatch: | |
| release: | |
| types: [published] | |
| jobs: | |
| name: Deploy API documentation | |
| permissions: | |
| contents: read | |
| on: | |
| workflow_dispatch: | |
| release: | |
| types: [published] | |
| push: | |
| paths: | |
| - 'api/specs/**' | |
| pull_request: | |
| paths: | |
| - 'api/specs/**' | |
| jobs: |
api/specs/api-v3.1.yaml
Outdated
| pattern: /^[A-Z ]{3}$/ | ||
| minLength: 3 |
There was a problem hiding this comment.
Fix regex pattern syntax
The pattern for last_name_trunc has incorrect regex syntax.
- pattern: /^[A-Z ]{3}$/
+ pattern: ^[A-Z ]{3}$📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| pattern: /^[A-Z ]{3}$/ | |
| minLength: 3 | |
| pattern: ^[A-Z ]{3}$ | |
| minLength: 3 |
api/specs/api-v3.1.yaml
Outdated
| pattern: /^[0-9A-Za-z_-]{0,32}$/ | ||
| message: |
There was a problem hiding this comment.
Fix regex pattern syntax
The pattern for cancel code has incorrect regex syntax.
- pattern: /^[0-9A-Za-z_-]{0,32}$/
+ pattern: ^[0-9A-Za-z_-]{0,32}$📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| pattern: /^[0-9A-Za-z_-]{0,32}$/ | |
| message: | |
| pattern: ^[0-9A-Za-z_-]{0,32}$ | |
| message: |
api/specs/api-v3.1.yaml
Outdated
| pattern: /^\+[0-9]{8,12}$/ | ||
| minLength: 10 |
There was a problem hiding this comment.
Fix regex pattern syntax
The pattern for phone_trunc has incorrect regex syntax.
- pattern: /^\+[0-9]{8,12}$/
+ pattern: ^\+[0-9]{8,12}$📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| pattern: /^\+[0-9]{8,12}$/ | |
| minLength: 10 | |
| pattern: ^\+[0-9]{8,12}$ | |
| minLength: 10 |
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Outside diff range and nitpick comments (2)
api/specs/api-v3.1.yaml (2)
846-853: Add more details about validation processThe validation section should provide more information about the asynchronous verification process.
Add the following details to the validation section:
### Validation Le schéma de données est présenté au format [JSON Schema Draft-07](https://json-schema.org/understanding-json-schema/index.html). + +### Processus de validation + +La validation se déroule en plusieurs étapes : +1. Validation syntaxique du payload (synchrone) +2. Vérification des données métier (asynchrone) +3. Détection de fraude (asynchrone) +4. Détection d'anomalies (asynchrone) ### Vérification Les vérifications sont faites de manière asynchrone. Le statut ne peut plus changer 48h après la date de fin du trajet. En cas d'indisponibilité du ou des services, le trajet est considéré comme `ok` après 48h🧰 Tools
🪛 yamllint (1.35.1)
[error] 846-846: trailing spaces
(trailing-spaces)
904-921: Add rate limiting information to response headersThe API implements rate limiting but the response headers are not documented in the OpenAPI spec.
Add rate limiting headers to the response schema:
responses: '201': description: OK. Le trajet a bien été enregistré. headers: + RateLimit-Limit: + schema: + type: integer + description: Nombre total de requêtes entre deux réinitialisations de quota + RateLimit-Remaining: + schema: + type: integer + description: Nombre de requêtes jusqu'à la réinitialisation du quota + RateLimit-Reset: + schema: + type: integer + description: Temps restant (en secondes) jusqu'à la réinitialisation du quota content: 'application/json':🧰 Tools
🪛 yamllint (1.35.1)
[warning] 909-909: wrong indentation: expected 14 but found 15
(indentation)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (2)
.github/workflows/deploy-techdoc.yaml(1 hunks)api/specs/api-v3.1.yaml(1 hunks)
🧰 Additional context used
🪛 yamllint (1.35.1)
api/specs/api-v3.1.yaml
[error] 17-17: trailing spaces
(trailing-spaces)
[error] 90-90: trailing spaces
(trailing-spaces)
[error] 386-386: trailing spaces
(trailing-spaces)
[error] 447-447: trailing spaces
(trailing-spaces)
[warning] 453-453: wrong indentation: expected 6 but found 8
(indentation)
[error] 501-501: trailing spaces
(trailing-spaces)
[warning] 688-688: wrong indentation: expected 12 but found 10
(indentation)
[warning] 692-692: wrong indentation: expected 12 but found 10
(indentation)
[error] 742-742: trailing spaces
(trailing-spaces)
[error] 774-774: trailing spaces
(trailing-spaces)
[warning] 819-819: wrong indentation: expected 8 but found 6
(indentation)
[error] 846-846: trailing spaces
(trailing-spaces)
[warning] 909-909: wrong indentation: expected 14 but found 15
(indentation)
[warning] 954-954: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1016-1016: wrong indentation: expected 8 but found 6
(indentation)
[error] 1076-1076: trailing spaces
(trailing-spaces)
[warning] 1106-1106: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1152-1152: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1257-1257: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1289-1289: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1317-1317: wrong indentation: expected 8 but found 6
(indentation)
[error] 1338-1338: trailing spaces
(trailing-spaces)
[error] 1346-1346: trailing spaces
(trailing-spaces)
[error] 1362-1362: trailing spaces
(trailing-spaces)
[error] 1433-1433: trailing spaces
(trailing-spaces)
[warning] 1437-1437: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1570-1570: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1674-1674: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1763-1763: wrong indentation: expected 8 but found 6
(indentation)
[error] 1797-1797: trailing spaces
(trailing-spaces)
[warning] 1820-1820: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1869-1869: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1894-1894: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1919-1919: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1945-1945: wrong indentation: expected 8 but found 6
(indentation)
[error] 1957-1957: trailing spaces
(trailing-spaces)
.github/workflows/deploy-techdoc.yaml
[error] 15-15: trailing spaces
(trailing-spaces)
🔇 Additional comments (7)
.github/workflows/deploy-techdoc.yaml (5)
2-3: Remove unnecessary permissions
The workflow only performs documentation deployment using the bump.sh action, which only requires read access to repository contents. The current permissions configuration is correct and minimal.
31-37: 🛠️ Refactor suggestion
Add OpenAPI syntax validation
The file existence check is good, but we should also validate the OpenAPI syntax.
This was previously suggested in past review comments. The validation step should be added after the file existence check.
4-10: 🛠️ Refactor suggestion
Update workflow triggers configuration
The current trigger configuration has several issues:
- The workflow is triggered on pushes to a temporary feature branch
- Missing triggers for automated deployments on documentation changes
Apply this diff to improve the trigger configuration:
on:
workflow_dispatch:
release:
types: [published]
push:
- branches:
- - chore/add-bump-action
+ paths:
+ - 'api/specs/**'
+ branches:
+ - main
+ pull_request:
+ paths:
+ - 'api/specs/**'Likely invalid or redundant comment.
44-50: Verify the deployment configuration
The deployment step looks correct but let's verify the token configuration.
Run the following script to check if all required secrets are properly configured:
17-26: 🛠️ Refactor suggestion
Add missing API version to the matrix
The matrix strategy only includes v3.0 and v3.1 versions, but the codebase also contains v2.0 specifications.
Add v2.0 to the matrix configuration:
strategy:
matrix:
include:
+ - doc: api
+ version: v2.0
+ token: BUMP_TOKEN_API
- doc: api
version: v3.1
token: BUMP_TOKEN_API
- doc: api
version: v3.0
token: BUMP_TOKEN_APILikely invalid or redundant comment.
api/specs/api-v3.1.yaml (2)
1-25: LGTM: API metadata is well-documented
The API metadata section is comprehensive and includes all required information:
- Title and version
- Terms of service link
- Contact information
- License details
- Clear description in French
- Production and pre-production servers
🧰 Tools
🪛 yamllint (1.35.1)
[error] 17-17: trailing spaces
(trailing-spaces)
27-28: Security configuration is properly set
Global security requirement for bearer token authentication is correctly configured.
api/specs/api-v3.1.yaml
Outdated
| pattern: /^[a-z0-9]{1,256}$/ | ||
| minLength: 1 | ||
| maxLength: 256 |
There was a problem hiding this comment.
Fix regex pattern syntax in multiple schemas
Several regex patterns have incorrect syntax with leading and trailing forward slashes.
Apply these diffs to fix the regex patterns:
- operator_journey_id:
- pattern: /^[a-z0-9]{1,256}$/
+ pattern: ^[a-z0-9]{1,256}$- phone_trunc:
- pattern: /^\+[0-9]{8,12}$/
+ pattern: ^\+[0-9]{8,12}$- last_name_trunc:
- pattern: /^[A-Z ]{3}$/
+ pattern: ^[A-Z ]{3}$- cancel code:
- pattern: /^[0-9A-Za-z_-]{0,32}$/
+ pattern: ^[0-9A-Za-z_-]{0,32}$Also applies to: 433-434, 440-441, 1175-1176
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (4)
api/specs/api-v3.1.yaml (4)
27-28: Enhance security configuration with additional headersWhile the bearer token security is correctly configured, consider adding these security-related headers to enhance API security:
X-Content-Type-Options: nosniffStrict-Transport-Security: max-age=31536000; includeSubDomainsX-Frame-Options: DENYContent-Security-Policy: default-src 'none'
161-167: Enhance validation for monetary fieldsThe revenue and contribution fields could benefit from additional validation:
- Add a maximum value constraint to prevent unreasonable amounts
- Add examples to clarify the centimes format
Apply these changes:
revenue: type: number minimum: 0 + maximum: 1000000 multipleOf: 1 description: | La somme réellement perçue par le conducteur **APRÈS** que toutes les incitations (subventions employeurs, promotions opérateurs, incitations AOM, etc.), contributions des passagers aient été versées et que la commission de l'opérateur soit prise. Somme exprimée en centimes. + example: 1000 # 10€contribution: type: number minimum: 0 + maximum: 1000000 multipleOf: 1 description: | Coût réel total du service pour l'occupant passager en fonction du nombre de sièges réservés **APRÈS** que toutes les possibles incitations aient été versées (subventions employeurs, promotions opérateurs, incitations AOM, etc).| Somme exprimée en centimes. + example: 500 # 5€Also applies to: 179-185
92-102: Standardize rate limiting documentation across endpointsWhile rate limiting is well documented in the global section, consider:
- Adding rate limit information consistently to all endpoint descriptions
- Documenting the rate limit headers in the response schemas of all endpoints
Add the following to each endpoint's response schema:
headers: RateLimit-Limit: schema: type: integer description: Number of requests allowed in the current time window RateLimit-Remaining: schema: type: integer description: Number of remaining requests in the current time window RateLimit-Reset: schema: type: integer description: Time until the rate limit resets in seconds
1-1984: Consider using a YAML formatterThere are multiple formatting inconsistencies in the file (indentation and trailing spaces). Consider using a YAML formatter like
prettierwith theprettier-plugin-yamlplugin to maintain consistent formatting.🧰 Tools
🪛 yamllint (1.35.1)
[error] 17-17: trailing spaces
(trailing-spaces)
[error] 110-110: trailing spaces
(trailing-spaces)
[error] 406-406: trailing spaces
(trailing-spaces)
[error] 467-467: trailing spaces
(trailing-spaces)
[warning] 473-473: wrong indentation: expected 6 but found 8
(indentation)
[error] 521-521: trailing spaces
(trailing-spaces)
[warning] 708-708: wrong indentation: expected 12 but found 10
(indentation)
[warning] 712-712: wrong indentation: expected 12 but found 10
(indentation)
[error] 762-762: trailing spaces
(trailing-spaces)
[error] 794-794: trailing spaces
(trailing-spaces)
[warning] 839-839: wrong indentation: expected 8 but found 6
(indentation)
[error] 866-866: trailing spaces
(trailing-spaces)
[warning] 929-929: wrong indentation: expected 14 but found 15
(indentation)
[warning] 974-974: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1036-1036: wrong indentation: expected 8 but found 6
(indentation)
[error] 1096-1096: trailing spaces
(trailing-spaces)
[warning] 1126-1126: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1172-1172: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1277-1277: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1309-1309: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1337-1337: wrong indentation: expected 8 but found 6
(indentation)
[error] 1358-1358: trailing spaces
(trailing-spaces)
[error] 1366-1366: trailing spaces
(trailing-spaces)
[error] 1382-1382: trailing spaces
(trailing-spaces)
[error] 1453-1453: trailing spaces
(trailing-spaces)
[warning] 1457-1457: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1590-1590: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1694-1694: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1783-1783: wrong indentation: expected 8 but found 6
(indentation)
[error] 1817-1817: trailing spaces
(trailing-spaces)
[warning] 1840-1840: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1889-1889: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1914-1914: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1939-1939: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1965-1965: wrong indentation: expected 8 but found 6
(indentation)
[error] 1977-1977: trailing spaces
(trailing-spaces)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
api/specs/api-v3.1.yaml(1 hunks)
🧰 Additional context used
🪛 yamllint (1.35.1)
api/specs/api-v3.1.yaml
[error] 17-17: trailing spaces
(trailing-spaces)
[error] 110-110: trailing spaces
(trailing-spaces)
[error] 406-406: trailing spaces
(trailing-spaces)
[error] 467-467: trailing spaces
(trailing-spaces)
[warning] 473-473: wrong indentation: expected 6 but found 8
(indentation)
[error] 521-521: trailing spaces
(trailing-spaces)
[warning] 708-708: wrong indentation: expected 12 but found 10
(indentation)
[warning] 712-712: wrong indentation: expected 12 but found 10
(indentation)
[error] 762-762: trailing spaces
(trailing-spaces)
[error] 794-794: trailing spaces
(trailing-spaces)
[warning] 839-839: wrong indentation: expected 8 but found 6
(indentation)
[error] 866-866: trailing spaces
(trailing-spaces)
[warning] 929-929: wrong indentation: expected 14 but found 15
(indentation)
[warning] 974-974: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1036-1036: wrong indentation: expected 8 but found 6
(indentation)
[error] 1096-1096: trailing spaces
(trailing-spaces)
[warning] 1126-1126: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1172-1172: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1277-1277: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1309-1309: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1337-1337: wrong indentation: expected 8 but found 6
(indentation)
[error] 1358-1358: trailing spaces
(trailing-spaces)
[error] 1366-1366: trailing spaces
(trailing-spaces)
[error] 1382-1382: trailing spaces
(trailing-spaces)
[error] 1453-1453: trailing spaces
(trailing-spaces)
[warning] 1457-1457: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1590-1590: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1694-1694: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1783-1783: wrong indentation: expected 8 but found 6
(indentation)
[error] 1817-1817: trailing spaces
(trailing-spaces)
[warning] 1840-1840: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1889-1889: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1914-1914: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1939-1939: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1965-1965: wrong indentation: expected 8 but found 6
(indentation)
[error] 1977-1977: trailing spaces
(trailing-spaces)
🔇 Additional comments (1)
api/specs/api-v3.1.yaml (1)
196-198:
Fix regex pattern syntax in multiple schemas
Several regex patterns have incorrect syntax with leading and trailing forward slashes.
Apply these diffs to fix the regex patterns:
- operator_journey_id:
- pattern: /^[a-z0-9]{1,256}$/
+ pattern: ^[a-z0-9]{1,256}$- phone_trunc:
- pattern: /^\+[0-9]{8,12}$/
+ pattern: ^\+[0-9]{8,12}$- last_name_trunc:
- pattern: /^[A-Z ]{3}$/
+ pattern: ^[A-Z ]{3}$- cancel code:
- pattern: /^[0-9A-Za-z_-]{0,32}$/
+ pattern: ^[0-9A-Za-z_-]{0,32}$Also applies to: 453-454, 460-461, 1195-1196
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Outside diff range and nitpick comments (1)
api/specs/api-v3.1.yaml (1)
17-17: Fix formatting issuesThe YAML file has several formatting inconsistencies:
- Trailing spaces on multiple lines
- Inconsistent indentation
Consider using a YAML formatter to automatically fix these issues. For example:
yamlfmt api/specs/api-v3.1.yamlAlso applies to: 110-110, 406-406, 467-467, 521-521, 762-762, 794-794, 866-866, 1096-1096, 1358-1358, 1366-1366, 1382-1382, 1453-1453, 1817-1817, 1977-1977
🧰 Tools
🪛 yamllint (1.35.1)
[error] 17-17: trailing spaces
(trailing-spaces)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
api/specs/api-v3.1.yaml(1 hunks)
🧰 Additional context used
🪛 yamllint (1.35.1)
api/specs/api-v3.1.yaml
[error] 17-17: trailing spaces
(trailing-spaces)
[error] 110-110: trailing spaces
(trailing-spaces)
[error] 406-406: trailing spaces
(trailing-spaces)
[error] 467-467: trailing spaces
(trailing-spaces)
[warning] 473-473: wrong indentation: expected 6 but found 8
(indentation)
[error] 521-521: trailing spaces
(trailing-spaces)
[warning] 708-708: wrong indentation: expected 12 but found 10
(indentation)
[warning] 712-712: wrong indentation: expected 12 but found 10
(indentation)
[error] 762-762: trailing spaces
(trailing-spaces)
[error] 794-794: trailing spaces
(trailing-spaces)
[warning] 839-839: wrong indentation: expected 8 but found 6
(indentation)
[error] 866-866: trailing spaces
(trailing-spaces)
[warning] 929-929: wrong indentation: expected 14 but found 15
(indentation)
[warning] 974-974: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1036-1036: wrong indentation: expected 8 but found 6
(indentation)
[error] 1096-1096: trailing spaces
(trailing-spaces)
[warning] 1126-1126: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1172-1172: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1277-1277: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1309-1309: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1337-1337: wrong indentation: expected 8 but found 6
(indentation)
[error] 1358-1358: trailing spaces
(trailing-spaces)
[error] 1366-1366: trailing spaces
(trailing-spaces)
[error] 1382-1382: trailing spaces
(trailing-spaces)
[error] 1453-1453: trailing spaces
(trailing-spaces)
[warning] 1457-1457: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1590-1590: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1694-1694: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1783-1783: wrong indentation: expected 8 but found 6
(indentation)
[error] 1817-1817: trailing spaces
(trailing-spaces)
[warning] 1840-1840: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1889-1889: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1914-1914: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1939-1939: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1965-1965: wrong indentation: expected 8 but found 6
(indentation)
[error] 1977-1977: trailing spaces
(trailing-spaces)
🔇 Additional comments (2)
api/specs/api-v3.1.yaml (2)
27-28: LGTM! Global security requirement is properly configured.
The security configuration is correctly set up with bearer token authentication applied globally to all endpoints.
835-1983: Well-structured API endpoint definitions
The API endpoints are thoroughly documented with:
- Clear descriptions and examples
- Proper request/response schemas
- Comprehensive error handling
- Rate limiting information
🧰 Tools
🪛 yamllint (1.35.1)
[warning] 839-839: wrong indentation: expected 8 but found 6
(indentation)
[error] 866-866: trailing spaces
(trailing-spaces)
[warning] 929-929: wrong indentation: expected 14 but found 15
(indentation)
[warning] 974-974: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1036-1036: wrong indentation: expected 8 but found 6
(indentation)
[error] 1096-1096: trailing spaces
(trailing-spaces)
[warning] 1126-1126: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1172-1172: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1277-1277: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1309-1309: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1337-1337: wrong indentation: expected 8 but found 6
(indentation)
[error] 1358-1358: trailing spaces
(trailing-spaces)
[error] 1366-1366: trailing spaces
(trailing-spaces)
[error] 1382-1382: trailing spaces
(trailing-spaces)
[error] 1453-1453: trailing spaces
(trailing-spaces)
[warning] 1457-1457: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1590-1590: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1694-1694: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1783-1783: wrong indentation: expected 8 but found 6
(indentation)
[error] 1817-1817: trailing spaces
(trailing-spaces)
[warning] 1840-1840: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1889-1889: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1914-1914: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1939-1939: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1965-1965: wrong indentation: expected 8 but found 6
(indentation)
[error] 1977-1977: trailing spaces
(trailing-spaces)
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (4)
api/specs/api-v3.1.yaml (4)
26-27: Consider enhancing API security with additional security headersWhile bearer token authentication is correctly configured, consider adding security-related response headers to enhance API security:
security: - token: [] + x-security-headers: + X-Content-Type-Options: nosniff + X-Frame-Options: DENY + Strict-Transport-Security: max-age=31536000; includeSubDomains
20-24: Consider adding development/testing environmentsThe server configuration only includes production and pre-production environments. Consider adding development and testing environments to facilitate the development lifecycle:
servers: - url: https://api.covoiturage.beta.gouv.fr/v3.1 description: Production - url: https://api.demo.covoiturage.beta.gouv.fr/v3.1 description: Pré-production + - url: https://api.test.covoiturage.beta.gouv.fr/v3.1 + description: Test + - url: https://api.dev.covoiturage.beta.gouv.fr/v3.1 + description: Development
126-128: Add migration path for deprecated endpointsThe "Attestations opérateurs" endpoints are marked as deprecated. Consider adding information about:
- When these endpoints will be removed
- What endpoints should be used instead
- Migration guide for users
161-169: Consider more granular rate limitingThe current rate limiting is set to 20,000 requests per minute for journey submissions. Consider:
- Different rate limits for different operations based on their resource intensity
- User-based rate limits in addition to endpoint-based limits
- Burst limits to handle traffic spikes
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
api/specs/api-v3.1.yaml(1 hunks)
🧰 Additional context used
🪛 yamllint (1.35.1)
api/specs/api-v3.1.yaml
[error] 17-17: trailing spaces
(trailing-spaces)
[error] 36-36: trailing spaces
(trailing-spaces)
[error] 182-182: trailing spaces
(trailing-spaces)
[error] 478-478: trailing spaces
(trailing-spaces)
[error] 539-539: trailing spaces
(trailing-spaces)
[warning] 545-545: wrong indentation: expected 6 but found 8
(indentation)
[error] 593-593: trailing spaces
(trailing-spaces)
[warning] 780-780: wrong indentation: expected 12 but found 10
(indentation)
[warning] 784-784: wrong indentation: expected 12 but found 10
(indentation)
[error] 834-834: trailing spaces
(trailing-spaces)
[error] 866-866: trailing spaces
(trailing-spaces)
[warning] 911-911: wrong indentation: expected 8 but found 6
(indentation)
[error] 938-938: trailing spaces
(trailing-spaces)
[warning] 1001-1001: wrong indentation: expected 14 but found 15
(indentation)
[warning] 1046-1046: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1108-1108: wrong indentation: expected 8 but found 6
(indentation)
[error] 1168-1168: trailing spaces
(trailing-spaces)
[warning] 1198-1198: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1244-1244: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1349-1349: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1381-1381: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1409-1409: wrong indentation: expected 8 but found 6
(indentation)
[error] 1430-1430: trailing spaces
(trailing-spaces)
[error] 1438-1438: trailing spaces
(trailing-spaces)
[error] 1454-1454: trailing spaces
(trailing-spaces)
[error] 1525-1525: trailing spaces
(trailing-spaces)
[warning] 1529-1529: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1662-1662: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1766-1766: wrong indentation: expected 8 but found 6
(indentation)
[warning] 1855-1855: wrong indentation: expected 8 but found 6
(indentation)
[error] 1860-1860: trailing spaces
(trailing-spaces)
[error] 1864-1864: trailing spaces
(trailing-spaces)
[error] 1898-1898: trailing spaces
(trailing-spaces)
[warning] 1921-1921: wrong indentation: expected 8 but found 6
(indentation)
[error] 1927-1927: trailing spaces
(trailing-spaces)
[warning] 1974-1974: wrong indentation: expected 8 but found 6
(indentation)
[error] 1982-1982: trailing spaces
(trailing-spaces)
[warning] 2005-2005: wrong indentation: expected 8 but found 6
(indentation)
[warning] 2030-2030: wrong indentation: expected 8 but found 6
(indentation)
[warning] 2056-2056: wrong indentation: expected 8 but found 6
(indentation)
[error] 2068-2068: trailing spaces
(trailing-spaces)
🔇 Additional comments (1)
api/specs/api-v3.1.yaml (1)
268-268:
Fix regex pattern syntax in multiple schemas
The regex patterns have incorrect syntax with leading and trailing forward slashes that need to be removed:
# operator_journey_id pattern
- pattern: /^[a-z0-9]{1,256}$/
+ pattern: ^[a-z0-9]{1,256}$
# phone_trunc pattern
- pattern: /^\+[0-9]{8,12}$/
+ pattern: ^\+[0-9]{8,12}$
# last_name_trunc pattern
- pattern: /^[A-Z ]{3}$/
+ pattern: ^[A-Z ]{3}$
# cancel code pattern
- pattern: /^[0-9A-Za-z_-]{0,32}$/
+ pattern: ^[0-9A-Za-z_-]{0,32}$Also applies to: 525-526, 532-533, 1267-1268
Summary by CodeRabbit
New Features
Bug Fixes
Documentation