-
-
Notifications
You must be signed in to change notification settings - Fork 383
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: Make api.yml a valid OpenAPI-3.1.0-Spec #8042
docs: Make api.yml a valid OpenAPI-3.1.0-Spec #8042
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thank you!
Thank you very much @sgtSeme4ki. We should add a test to make sure the files pass validation. |
I'm tried to add a github-action which validates the openApiSpec. Unfortunately the specific gitHubAction can't validate openApiSpecs with the 3.1.0-Version. I will try to use the OpenApiValidator (which I used locally) as a gitHub-Action to validate the openApiSpec. |
@sgtSeme4ki thank you so much for this :-) What about using https://pypi.org/project/openapi-spec-validator/ for validation, it says it supports OpenAPI 3.1 |
I tried the validator you mentioned, but while validating it gave me a python error "string indices must be integers". There is probably an Error while validation which isn't covered by this validator. I used the validator which is included in the openApiGenerator and included it as a docker run (https://openapi-generator.tech/docs/installation/). I also made some small fixes in the OpenApiSpec so that the validator validates without errors. |
Thank you very much @sgtSeme4ki ! @alexgarel : can we merge? |
…api-spec-validator 0.5.4
…api-spec-validator 0.5.4
Kudos, SonarCloud Quality Gate passed! 0 Bugs No Coverage information |
Since this merge, the OpenAPI schemas have changed path. @alexgarel this docs restructure was committed by you. Since then neither
This may be a regression, were the latest API schemas 'clobbered' by older invalid versions in the doc restructure? |
|
Hi everyone, I wanted to bring to your attention a related issue that might provide additional context or insights into this bug. You can view the discussion and details here: Issue #9419 - Comment. Feel free to review it and see if it helps in resolving the current issue. |
feat(api): improve OpenAPI schema consistency and structure ### What This pull request enhances the consistency and structure of OpenAPI schemas in the Open Food Facts project. The main changes include: - Added missing titles to response and request schemas for better identification - Standardized schema references using #/components/schemas/ for improved consistency - Removed unnecessary x-stoplight metadata - Fixed inconsistencies in data types and enums - Improved descriptions and examples in various schemas - Restructured the image_role schema for better organization - Updated the product schema to use centralized component references These changes improve the readability, maintainability, and consistency of the API definition, making it easier for developers to use and integrate. The updated schema has been tested with the following OpenAPI generators and tools: - OpenAPI Generator: - typescript-fetch - typescript - javascript - @hey-api/openapi-ts - Swagger Editor (editor-next.swagger.io) The primary configuration used for testing was: ```yaml generatorName: typescript-fetch outputDir: ./clients/ts-fetch inputSpec: ./fork-shinjigi-4pullrequest-api-ref/api.yml verbose: false additionalProperties: npmName: "@iside/ec-open-food-facts-client-ts-fetch" npmVersion: "1.122.0" npmRepository: "http://" snapshot: false supportsES6: false modelPropertyNaming: "original" enumPropertyNaming: "original" paramNaming: "original" enablePostProcessFile: true modelNameMappings: ingredient_1: Ingredient product_extended_owner_fields_1: ProductExtendedOwnerFields product_extended_owner_fields_1_additionalProperties: ProductExtendedOwnerFieldsAdditionalProperties product_ecoscore_data_1: ProductEcoscoreData globalProperties: debugOpenAPI: true ``` ### Screenshot ![graph](https://github.com/user-attachments/assets/05da6b7c-ad85-4217-bbf3-57339fd6d883) https://github.com/user-attachments/assets/61f50394-8992-4b8e-bd9c-76c8c138390a ### Related issue(s) and discussion - Fixes/RelatedTo: #8039 #8042
What
The api.yaml (including tags_parameters.yaml and product.yaml) where invalid while validation via openapi-generator validate. The validation issues were fixed to make api.yaml a valid 3.1.0 openAPI-Spec so it can be used by clients for client-code generation via the openAPI-Generator plugin etc.
Screenshot
Related issue(s) and discussion