MAJ OpenAPI V3.1 #2715
MAJ OpenAPI V3.1 #2715
Conversation
WalkthroughThe changes in this pull request introduce several updates across multiple files. A new GitHub pull request template is added to enhance the structure of contributions, emphasizing coding guidelines and documentation updates. The deployment workflows are modified to remove the "techdoc" project and introduce a new workflow for deploying API documentation. Additionally, new OpenAPI specifications for versions 2.0 and 3.0 of an API are created, detailing endpoints, schemas, and security mechanisms. 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: 4
🧹 Outside diff range and nitpick comments (8)
.github/workflows/deploy-techdoc.yaml (2)
15-15: Remove trailing whitespace.There is a trailing whitespace on line 15.
- +🧰 Tools
🪛 yamllint (1.35.1)
[error] 15-15: trailing spaces
(trailing-spaces)
39-42: Add error handling for OpenAPI validation step.The validation step should have error handling to provide better feedback when validation fails.
- name: Validate OpenAPI syntax uses: swaggerexpert/swagger-editor-validate@v1 + continue-on-error: false with: definition-file: api/specs/${{ matrix.doc }}-${{ matrix.version }}.yaml + id: validate + - name: Handle validation failure + if: steps.validate.outcome == 'failure' + run: | + echo "OpenAPI validation failed. Please check the specification for errors." + exit 1api/specs/api-v2.0.yaml (2)
168-220: Add descriptions for required fields in identity schema.The
identityschema has required fields in nested objects (e.g.,travel_pass.name,travel_pass.user_id) that lack descriptions.name: enum: - navigo - description: Nom du titre + description: Type du titre de transport. Actuellement seul 'navigo' est supporté. example: navigo user_id: type: string - description: Numéro de carte de transport + description: Identifiant unique du titre de transport de l'utilisateur example: 00-MFR-6782929🧰 Tools
🪛 yamllint (1.35.1)
[error] 196-196: trailing spaces
(trailing-spaces)
683-689: Add descriptions for required request body fields.The journey creation endpoint's required fields (
journey_id,operator_class,driver,passenger) lack descriptions in the schema.required: - journey_id - operator_class - driver - passenger additionalProperties: false + description: | + Required fields for journey creation: + - journey_id: Unique identifier for the journey + - operator_class: Class of proof (A, B, or C) + - driver: Driver information and journey details + - passenger: Passenger information and journey details properties:api/specs/api-v3.0.yaml (2)
503-544: Add rate limiting headers to API specification.While rate limiting is mentioned in the description (20000 requests per minute), it should be formally documented in the API specification using response headers.
Add the following response headers to document rate limiting:
responses: '201': description: OK. Le trajet a bien été enregistré. headers: + X-RateLimit-Limit: + schema: + type: integer + description: The number of allowed requests in the current period + X-RateLimit-Remaining: + schema: + type: integer + description: The number of remaining requests in the current period + X-RateLimit-Reset: + schema: + type: integer + description: The number of seconds left in the current period🧰 Tools
🪛 yamllint (1.35.1)
[warning] 507-507: wrong indentation: expected 8 but found 6
(indentation)
1-1453: Fix YAML formatting inconsistencies.There are several formatting issues in the YAML file:
- Inconsistent indentation (e.g., lines 507, 636, 698)
- Trailing spaces (e.g., lines 759, 1027, 1036)
Consider using a YAML formatter to maintain consistent formatting throughout the file.
🧰 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)
.github/pull_request_template.md (2)
1-13: Fix markdown formatting issues.The PR template has some markdown formatting issues:
- Missing space after # in heading (line 1)
- Consider adding a description placeholder with common sections
Apply these changes:
-#fixes (issues) +# Fixes (Issues)Also consider adding a structured description template:
## Description ### What changed <!-- Describe the changes you've made --> ### Why this change is needed <!-- Explain the motivation for these changes --> ### How it was tested <!-- Describe your testing approach -->🧰 Tools
🪛 Markdownlint (0.35.0)
1-1: null
No space after hash on atx style heading(MD018, no-missing-space-atx)
14-39: Enhance commit message format documentation.While the Angular commit convention is well documented, consider making it more user-friendly:
- Add examples for each commit type
- Consider adding a commit message template file
Add a
.gitmessagetemplate to the repository:+# Add a new file: .gitmessage +<type>(<scope>): <summary> + +# Example types: build|ci|docs|feat|fix|perf|refactor|test +# Example scopes: proxy|acquisition|export +# Summary: Present tense, no period, 50 chars or less + +# Details about the change (72 chars per line) + +# Include any breaking changes or issues closedThen users can set it as their commit template:
git config commit.template .gitmessage🧰 Tools
🪛 Markdownlint (0.35.0)
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)
19-19: null
Fenced code blocks should have a language specified(MD040, fenced-code-language)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (5)
.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)
🧰 Additional context used
🪛 yamllint (1.35.1)
.github/workflows/deploy-techdoc.yaml
[error] 15-15: trailing spaces
(trailing-spaces)
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-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)
🪛 checkov (3.2.312)
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-v2.0.yaml
[HIGH] 1-1079: Ensure that the global security field has rules defined
(CKV_OPENAPI_4)
🪛 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)
🔇 Additional comments (3)
.github/workflows/deploy-techdoc.yaml (1)
2-3: LGTM! Good security practice with minimal permissions.
The workflow correctly specifies minimal required permissions.
.github/workflows/deploy-frontends-many.yml (1)
25-25: LGTM! Correctly removes techdoc from deployment matrix.
The change aligns with moving API documentation deployment to its own workflow.
api/specs/api-v2.0.yaml (1)
1-1059: Verify OpenAPI specification version compatibility.
The PR objectives mention updating to OpenAPI v3.1, but this specification uses v3.0.2. Please verify if this is intentional or if it needs to be updated.
✅ Verification successful
The search results show that there are multiple API specification files with different versions:
- api-v3.1.yaml: OpenAPI 3.0.3
- api-v3.0.yaml: OpenAPI 3.0.2
- api-v2.0.yaml: OpenAPI 3.0.2 (the file under review)
Let me check the PR description and related files to understand the context better.
Let me check the documentation files to understand if there's any planned migration to OpenAPI 3.1 or if the current version is intentional.
Let me check the actual changes in the v3.1 specification file since it was modified in this PR.
Based on the investigation, I can now provide a final response:
The OpenAPI version 3.0.2 in api-v2.0.yaml is correct and should be maintained
The codebase maintains multiple API versions with their respective OpenAPI specifications:
- api-v2.0.yaml (under review): OpenAPI 3.0.2
- api-v3.0.yaml: OpenAPI 3.0.2
- api-v3.1.yaml: OpenAPI 3.0.3
While the PR objectives mentioned updating to OpenAPI v3.1, this appears to refer to the API version (v3.1) rather than the OpenAPI specification version. This is evidenced by the fact that even the latest API spec (api-v3.1.yaml) uses OpenAPI 3.0.3, not 3.1.x. The version 3.0.2 in api-v2.0.yaml should be maintained for backward compatibility.
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash
# Check OpenAPI versions across specification files
echo "Checking OpenAPI versions in specification files..."
rg -A 1 "openapi:" api/specs/
Length of output: 359
Script:
#!/bin/bash
# Check PR description and related files
echo "Checking PR files..."
git show --name-status HEAD
# Check if there are any migration guides or documentation
echo -e "\nChecking for migration/upgrade documentation..."
fd -t f -e md -e txt | xargs rg -l "openapi|migration|upgrade"
Length of output: 683
Script:
#!/bin/bash
# Check API documentation for OpenAPI version requirements
echo "Checking API documentation..."
rg -A 5 "openapi" doc/docs/contribuer/api/README.md
# Check if there are any pending migrations or version updates planned
echo -e "\nChecking for migration plans..."
rg "3\.1|migration" doc/docs/contribuer/api/README.md
Length of output: 301
Script:
#!/bin/bash
# Check the changes in v3.1 spec
echo "Checking changes in v3.1 spec..."
git show HEAD:api/specs/api-v3.1.yaml | head -n 5
# Check if there are any related issues or PRs
echo -e "\nChecking commit messages for related changes..."
git log --grep="openapi" --grep="3.1" -i --pretty=format:"%h %s" -n 5
Length of output: 467
🧰 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)
🪛 checkov (3.2.312)
[HIGH] 1-1079: Ensure that the global security field has rules defined
(CKV_OPENAPI_4)
| openapi: '3.0.2' | ||
| info: | ||
| title: API | ||
| version: '2.0' | ||
| termsOfService: https://doc.covoiturage.beta.gouv.fr/le-registre-de-preuve-de-covoiturage/kit-de-communication/cgu-conditions-generales-dutilisation | ||
| contact: | ||
| name: Équipe technique | ||
| email: [email protected] | ||
| license: | ||
| name: Apache 2 | ||
| url: https://raw.githubusercontent.com/betagouv/preuve-covoiturage/main/LICENSE | ||
|
|
||
| externalDocs: | ||
| url: https://doc.covoiturage.beta.gouv.fr/ | ||
| description: Documentation générale | ||
|
|
||
| servers: | ||
| - url: https://api.covoiturage.beta.gouv.fr/v2 | ||
| - url: https://api.demo.covoiturage.beta.gouv.fr/v2 | ||
|
|
||
| components: | ||
| securitySchemes: | ||
| token: | ||
| type: http | ||
| scheme: bearer | ||
| bearerFormat: JWT | ||
| schemas: |
There was a problem hiding this comment.
Add global security requirement for bearer token authentication.
The API requires bearer token authentication but it's not enforced globally. This is a security risk as endpoints might accidentally be left without authentication requirements.
openapi: '3.0.2'
+security:
+ - token: []
info:
title: API
version: '2.0'📝 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.
| openapi: '3.0.2' | |
| info: | |
| title: API | |
| version: '2.0' | |
| termsOfService: https://doc.covoiturage.beta.gouv.fr/le-registre-de-preuve-de-covoiturage/kit-de-communication/cgu-conditions-generales-dutilisation | |
| contact: | |
| name: Équipe technique | |
| email: [email protected] | |
| license: | |
| name: Apache 2 | |
| url: https://raw.githubusercontent.com/betagouv/preuve-covoiturage/main/LICENSE | |
| externalDocs: | |
| url: https://doc.covoiturage.beta.gouv.fr/ | |
| description: Documentation générale | |
| servers: | |
| - url: https://api.covoiturage.beta.gouv.fr/v2 | |
| - url: https://api.demo.covoiturage.beta.gouv.fr/v2 | |
| components: | |
| securitySchemes: | |
| token: | |
| type: http | |
| scheme: bearer | |
| bearerFormat: JWT | |
| schemas: | |
| openapi: '3.0.2' | |
| security: | |
| - token: [] | |
| info: | |
| title: API | |
| version: '2.0' | |
| termsOfService: https://doc.covoiturage.beta.gouv.fr/le-registre-de-preuve-de-covoiturage/kit-de-communication/cgu-conditions-generales-dutilisation | |
| contact: | |
| name: Équipe technique | |
| email: [email protected] | |
| license: | |
| name: Apache 2 | |
| url: https://raw.githubusercontent.com/betagouv/preuve-covoiturage/main/LICENSE | |
| externalDocs: | |
| url: https://doc.covoiturage.beta.gouv.fr/ | |
| description: Documentation générale | |
| servers: | |
| - url: https://api.covoiturage.beta.gouv.fr/v2 | |
| - url: https://api.demo.covoiturage.beta.gouv.fr/v2 | |
| components: | |
| securitySchemes: | |
| token: | |
| type: http | |
| scheme: bearer | |
| bearerFormat: JWT | |
| schemas: |
🧰 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)
| identity: | ||
| type: object | ||
| description: | | ||
| Ces données personnelles permettent d'identifier la personne effectuant le covoiturage afin de pouvoir comptabiliser ses trajets et lui distribuer des incitations en fonction des politiques applicables. | ||
| Deux options sont disponibles pour la transmission du numéro de téléphone : | ||
| - Numéro complet au format ITU E.164 (phone) (ex. +33601020304, +590690101010) | ||
| - Numéro au format ITU E.164 tronqué des 2 derniers chiffres (phone_trunc) (ex. +336010203, +5906901010) + identifiant unique de l'opérateur (operator_user_id) | ||
| additionalProperties: false | ||
| required: | ||
| - operator_user_id | ||
| - identity_key | ||
| - phone_trunc | ||
| properties: | ||
| identity_key: | ||
| type: string | ||
| minLength: 64 | ||
| maxLength: 64 | ||
| description: | | ||
| Correspond au SHA d'une chaîne concaténée tel que : sha256(*phone_number*-*last_name*) ou | ||
| - `phone_number` correspond au numéro de téléphone complet au format international sans espace ni tiret. Exemple : +33601020304 | ||
| - `last_name` correspond au nom de famille complet en majuscule, sans accent ni tiret ni apostrophe (regexp: [A-Z ]*) | ||
| Par exemple, M. D'Hérûg-de-l'Hérault ayant le numéro 07 01 02 03 04 doit être formatté comme suit "+33701020304-D HERUG DE L HERAULT" | ||
| travel_pass: | ||
| type: object | ||
| description: | | ||
| Numéro de carte de transport (TCL, Navigo, Trabool, etc.) de l'occupant. | ||
| Obligatoire si l'information est disponible. | ||
| Actuellement supporté: Navigo | ||
| additionalProperties: false | ||
| required: | ||
| - name | ||
| - user_id | ||
| properties: | ||
| name: | ||
| enum: | ||
| - navigo | ||
| description: Nom du titre | ||
| example: navigo | ||
| user_id: | ||
| type: string | ||
| description: Numéro de carte de transport | ||
| example: 00-MFR-6782929 | ||
| phone: | ||
| type: string | ||
| description: Numéro au format ITU E.164 | ||
| example: '+33601020304, +590690101010' | ||
| phone_trunc: | ||
| type: string | ||
| description: Numéro au format ITU E.164 tronqué des 2 derniers chiffres. Obligatoire si `phone` n'est pas renseigné. | ||
| example: '+336010203, +5906901010' | ||
| driving_license: | ||
| description: | | ||
| Numéro de permis de conduire (également appelé code driving_license) | ||
| cf https://permisdeconduire.ants.gouv.fr/tout-savoir-sur-le-permis/le-numero-de-dossier-sur-un-permis-au-format-carte-bancaire | ||
| oneOf: | ||
| - type: string | ||
| description: Numéro de permis de conduire composé de 12 chiffres après 1975. | ||
| example: '051227308989' | ||
| pattern: /^[0-9]{12}$/ | ||
| minLength: 12 | ||
| maxLength: 12 | ||
| - type: string | ||
| description: Numéro de permis de conduire composé de 1 à 15 caractères suivis de 4 chiffres avant 1975. | ||
| example: '822146819' | ||
| pattern: /^[A-Z0-9]{1,15}[0-9]{4}$/ | ||
| minLength: 5 | ||
| maxLength: 19 | ||
| - type: string | ||
| description: Numéro de permis de conduire plus anciens composé de 1 à 15 caractères. | ||
| example: '123456A' | ||
| pattern: /^[A-Z0-9]{1,15}$/ | ||
| minLength: 1 | ||
| maxLength: 15 | ||
| - type: string | ||
| description: Numéro de permis étranger préfixé de l'indicatif '99-'. | ||
| example: '99-X23836' | ||
| pattern: /^99-.*$/ | ||
| minLength: 4 | ||
| maxLength: 64 | ||
| operator_user_id: | ||
| type: string | ||
| description: Identifiant de l'utilisateur chez l'opérateur. Obligatoire. | ||
| example: "d2e8a6c4-9e3a-4b6f-8e8d-9f7a6b5c4d3e" | ||
| over_18: |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Enhance PII data handling in identity schema.
The identity schema handles sensitive personal information (phone numbers, names). While the implementation includes truncation for privacy, consider additional security measures:
- Add a note about GDPR compliance requirements
- Consider implementing data masking for logging
- Add validation for international phone numbers
🧰 Tools
🪛 yamllint (1.35.1)
[warning] 356-356: wrong indentation: expected 10 but found 12
(indentation)
| description: Identifiant du certificat précédemment créé. | ||
| required: true | ||
| schema: | ||
| type: string | ||
| format: uuid | ||
| post: | ||
| tags: | ||
| - Attestations | ||
| summary: Télécharger une attestation | ||
| description: | | ||
| ## Upload du logo opérateur | ||
|
|
||
| Vous pouvez personnaliser le logo opérateur présent sur l'attestation. | ||
|
|
||
| Contrairement aux meta-données envoyées lors de la création de l'attestation, le logo est configuré au préalable via le page de profil de votre opérateur. | ||
|
|
||
| - [Ajouter mon logo en production](https://app.covoiturage.beta.gouv.fr/admin/operator) | ||
| - [Ajouter mon logo pour les tests](https://app.demo.covoiturage.beta.gouv.fr/admin/operator) | ||
|
|
||
| > _Le poids de l'image est de 2Mo maximum et sa taille de 1024x1024 pixels._ | ||
|
|
||
| ## Téléchargement | ||
|
|
||
| Une fois l’attestation créée en base \(201 created\), on peut télécharger un PDF en y ajoutant des données permettant une identification simplifiée de la personne. | ||
|
|
||
| Ces meta-données optionnelles ne sont pas stockées sur nos serveurs, elles sont ajoutées au document généré à la volée. | ||
|
|
||
| Le PDF généré n'est pas stocké sur nos serveurs. L'appel d'API vous renvoie un fichier binaire que vous sauvegardez de votre côté. Vous pouvez générer le PDF d'une attestation plusieurs fois de suite. | ||
| security: | ||
| - token: [] | ||
| operationId: certificate:download | ||
| requestBody: | ||
| required: true | ||
| content: | ||
| 'application/json': | ||
| schema: | ||
| type: object | ||
| additionalProperties: false | ||
| properties: | ||
| meta: | ||
| type: object | ||
| description: | | ||
| personnalisation optionnelle de l'en-tête | ||
| omettre 'meta' si pas de personnalisation | ||
| toutes les propriétés sont facultatives | ||
| properties: | ||
| operator: | ||
| type: string | ||
| maxLength: 305 | ||
| description: | | ||
| zone de texte. Maximum de 305 caractères | ||
| Maximum de 6 lignes séparées par \n | ||
| identity: | ||
| type: object | ||
| properties: | ||
| name: | ||
| type: string | ||
| maxLength: 26 | ||
| description: Nom de la personne | ||
| content: | ||
| type: string | ||
| maxLength: 305 | ||
| description: | | ||
| zone de texte. Maximum de 305 caractères | ||
| Maximum de 6 lignes séparées par \n | ||
| note: | ||
| type: string | ||
| description: | | ||
| zone de texte. Maximum de 440 caractères | ||
| Retour à la ligne automatique | ||
|
|
||
| responses: | ||
| '200': | ||
| description: | | ||
| OK, le fichier binaire est envoyé. | ||
|  | ||
| '401': | ||
| description: Non authentifié. Le token applicatif est manquant ou invalide | ||
| content: | ||
| 'application/json': | ||
| example: | ||
| code: 401 | ||
| error: Unauthorized | ||
| '403': | ||
| description: | | ||
| Accès refusé | ||
| Les permissions de votre token applicatif ne vous permettent pas de créer une attestation. | ||
| Vous pouvez générer un nouveau token et réessayer. Si le problème persiste, [contactez notre équipe](mailto:[email protected]). | ||
| content: | ||
| 'application/json': | ||
| example: | ||
| code: 403 | ||
| error: Forbidden | ||
| '404': | ||
| description: L'attestation n'a pu être trouvée | ||
| content: | ||
| 'application/json': | ||
| example: | ||
| code: 404 | ||
| error: Not found |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Enhance security for certificate file handling.
The certificate attachment endpoint needs additional security measures:
- Add content-type validation
- Specify maximum file size in the OpenAPI spec
- Document virus scanning requirements
Add content type and size validation:
post:
requestBody:
required: true
content:
'application/json':
+ x-content-type-options: nosniff
+ x-frame-options: DENY
schema:
type: object
+ maxLength: 2097152 # 2MB limitCommittable suggestion skipped: line range outside the PR's diff.
🧰 Tools
🪛 yamllint (1.35.1)
[warning] 1263-1263: wrong indentation: expected 8 but found 6
(indentation)
| openapi: '3.0.2' | ||
| info: | ||
| title: API Trajets | ||
| version: "3.0" | ||
| 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) | ||
|
|
||
| ℹ️ _Contactez [notre équipe](mailto:[email protected]) pour obtenir un accès développeur sur l'application._ | ||
|
|
||
| ### Précisions d'usage | ||
|
|
||
| - Attention, l'API v3 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. | ||
|
|
||
| components: | ||
| securitySchemes: | ||
| token: | ||
| type: http | ||
| scheme: bearer | ||
| bearerFormat: JWT |
There was a problem hiding this comment.
Add global security requirements to ensure all endpoints require authentication by default.
While security schemes are properly defined, the specification is missing global security requirements. This could lead to endpoints accidentally being exposed without authentication if security is not explicitly defined for each operation.
Add the following at the root level of the specification:
openapi: '3.0.2'
info:
title: API Trajets
version: "3.0"
+ security:
+ - token: []📝 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.
| openapi: '3.0.2' | |
| info: | |
| title: API Trajets | |
| version: "3.0" | |
| 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) | |
| ℹ️ _Contactez [notre équipe](mailto:[email protected]) pour obtenir un accès développeur sur l'application._ | |
| ### Précisions d'usage | |
| - Attention, l'API v3 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. | |
| components: | |
| securitySchemes: | |
| token: | |
| type: http | |
| scheme: bearer | |
| bearerFormat: JWT | |
| openapi: '3.0.2' | |
| info: | |
| title: API Trajets | |
| version: "3.0" | |
| 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) | |
| ℹ️ _Contactez [notre équipe](mailto:[email protected]) pour obtenir un accès développeur sur l'application._ | |
| ### Précisions d'usage | |
| - Attention, l'API v3 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. | |
| security: | |
| - token: [] | |
| components: | |
| securitySchemes: | |
| token: | |
| type: http | |
| scheme: bearer | |
| bearerFormat: JWT |
🧰 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)
Description
Mise à jour et mise en forme du fichier openapi v3.1 pour Bump.sh
Checklist
Merge
Je squash la PR et vérifie que le message de commit utilise
la convention d'Angular :
Types de commit
Le scope (optionnel) précise le module ou le composant impacté par le commit.
Summary by CodeRabbit
New Features
Chores