Skip to content
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.

Sign up for GitHub

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

Jump to bottom

docs: Make api.yml a valid OpenAPI-3.1.0-Spec #8042

Merged
merged 10 commits into from
Feb 7, 2023
Merged

docs: Make api.yml a valid OpenAPI-3.1.0-Spec #8042

merged 10 commits into from
Feb 7, 2023

Conversation

sgtSeme4ki
Copy link
Contributor

@sgtSeme4ki sgtSeme4ki commented Jan 26, 2023 •
edited
Loading

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

  • Fixes #[8039]

@sgtSeme4ki sgtSeme4ki requested a review from a team as a code owner January 26, 2023 23:46
@github-actions github-actions bot added the 📚 Documentation Documentation issues improve the project for everyone. label Jan 26, 2023
@sgtSeme4ki sgtSeme4ki changed the title doc: Make api.yml a valid OpenAPI-3.1.0-Spec (checked via openapi-gene… doc: Make api.yml a valid OpenAPI-3.1.0-Spec Jan 26, 2023
@sgtSeme4ki sgtSeme4ki changed the title doc: Make api.yml a valid OpenAPI-3.1.0-Spec docs: Make api.yml a valid OpenAPI-3.1.0-Spec Jan 26, 2023
@sgtSeme4ki sgtSeme4ki mentioned this pull request Jan 26, 2023
Open
stephanegigandet
stephanegigandet approved these changes Jan 27, 2023
View reviewed changes
Copy link
Contributor

@stephanegigandet stephanegigandet left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you!

@stephanegigandet
Copy link
Contributor

Thank you very much @sgtSeme4ki. We should add a test to make sure the files pass validation.

@github-actions github-actions bot added the GitHub Actions Pull requests that update Github_actions code label Jan 30, 2023
@sgtSeme4ki
Copy link
Contributor Author

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.

@alexgarel
Copy link
Member

@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

@sgtSeme4ki
Copy link
Contributor Author

@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.

@stephanegigandet
Copy link
Contributor

Thank you very much @sgtSeme4ki !

@alexgarel : can we merge?

@sonarcloud
Copy link

sonarcloud bot commented Feb 7, 2023

Kudos, SonarCloud Quality Gate passed!    Quality Gate passed

Bug A 0 Bugs
Vulnerability A 0 Vulnerabilities
Security Hotspot A 0 Security Hotspots
Code Smell A 0 Code Smells

No Coverage information No Coverage information
0.0% 0.0% Duplication

@alexgarel alexgarel merged commit 8a99b8f into openfoodfacts:main Feb 7, 2023
@openfoodfacts-bot openfoodfacts-bot mentioned this pull request Feb 7, 2023
Merged
@chris-hatton
Copy link

chris-hatton commented Mar 18, 2023 •
edited
Loading

Since this merge, the OpenAPI schemas have changed path.

@alexgarel this docs restructure was committed by you. Since then neither api.yml or api-v3.yml are considered valid by:

  • VSCode OpenAPI editor
  • Gradle OpenAPI generation plugin

This may be a regression, were the latest API schemas 'clobbered' by older invalid versions in the doc restructure?

@alexgarel
Copy link
Member

alexgarel commented Mar 20, 2023 •
edited
Loading

@chris-hatton

  1. yes we renamed files for we reorganize documentation
  2. I think there is a problem with the validation tool that was setup, for me it reports a false positive, saying "is not an object" when I use #Product (json reference). See docs: fix open api documentation #8177
  3. feel free to fix it if you can, it would be great. But just take care that the documentation rendrering with rapidoc must continue to work.

@shinjigi
Copy link
Contributor

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.

@shinjigi shinjigi mentioned this pull request Oct 18, 2024
Merged
stephanegigandet pushed a commit that referenced this pull request Oct 21, 2024
@shinjigi
docs: Improve api def - tested ts client generation (#10913)
8cb1873 
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@alexgarel alexgarel alexgarel left review comments

@stephanegigandet stephanegigandet stephanegigandet approved these changes

Assignees

@sgtSeme4ki sgtSeme4ki

Labels
📚 Documentation Documentation issues improve the project for everyone. GitHub Actions Pull requests that update Github_actions code
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
5 participants
@sgtSeme4ki @stephanegigandet @alexgarel @chris-hatton @shinjigi