📝 API Documentation using OpenAPI (tracker)

teolemon commented 1 year ago

What

We are moving the API documentation away from https://github.com/openfoodfacts/api-documentation to the api-documentation, making it live next to the sourcecode, and migrating it from Postman format to OpenAPI.
The current output of the new OpenAPI doc is here.
This issue tracks this migration, and everything related to documentation
Tasklist

AUTH Requests

#### Reusable Data schemas
- [ ] Refactor product schema:
- [ ] Remove long examples (eg: do not list every possible in example countries, but keep two)
- [ ] https://github.com/openfoodfacts/openfoodfacts-server/issues/8132
- [ ] https://github.com/openfoodfacts/openfoodfacts-server/issues/8133
- [ ] https://github.com/openfoodfacts/openfoodfacts-server/issues/8131

Read Requests

##### Already partially documented Read requests
- [x] GET [Get for a specific product by barcode](https://openfoodfacts.github.io/openfoodfacts-server/reference/api/#tag/Read-Requests/operation/get-product-by-barcode)
- [x] GET [Performing OCR on a Product](https://openfoodfacts.github.io/openfoodfacts-server/reference/api/#tag/Read-Requests/operation/get-cgi-ingredients.pl)
- [x] GET [Search for Products](https://openfoodfacts.github.io/openfoodfacts-server/reference/api/#tag/Read-Requests/operation/get-search)
- [x] GET [Get Suggestions to Aid Adding/Editing Products](https://openfoodfacts.github.io/openfoodfacts-server/reference/api/#tag/Read-Requests/operation/get-cgi-suggest.pl)
- [ ] https://github.com/openfoodfacts/openfoodfacts-server/issues/8605

##### Improvements to READ requests
- [ ] GET product with only important / common fields (as done for [knowledge panels](https://openfoodfacts.github.io/openfoodfacts-server/reference/api/#tag/Read-Requests/operation/get-product-by-barcode-knowledge-panels))
- [ ] GET product with only images fields (as done for [knowledge panels](https://openfoodfacts.github.io/openfoodfacts-server/reference/api/#tag/Read-Requests/operation/get-product-by-barcode-knowledge-panels))

##### READ requests To be documented
- [ ] #7886
- [ ] #7887
- [ ] #7878
- [ ] #7879

Write Requests

### Already documented
- [x] POST [Add a Photo to an Existing Product](https://openfoodfacts.github.io/openfoodfacts-server/reference/api/#tag/Write-Requests/operation/get-cgi-product_image_upload.pl)
- [x] POST [Crop A Photo](https://openfoodfacts.github.io/openfoodfacts-server/reference/api/#tag/Write-Requests/operation/post-cgi-product_image_crop.pl)
- [x] GET [Rotate A Photo](https://openfoodfacts.github.io/openfoodfacts-server/reference/api/#tag/Write-Requests/operation/get-cgi-product_image_crop.pl)
- [x] POST [Add or Edit A Product](https://openfoodfacts.github.io/openfoodfacts-server/reference/api/#tag/Write-Requests/operation/post-cgi-product_jqm2.pl)

### To be documented
- [ ] add parameters to [Add or Edit A Product](https://openfoodfacts.github.io/openfoodfacts-server/reference/api/#tag/Write-Requests/operation/post-cgi-product_jqm2.pl) re-using parts of product schema
- [ ] Transfer https://github.com/openfoodfacts/api-documentation/issues/15 to OpenAPI
- [ ] #7881
- [x] #7880
- [ ] #7882
- [ ] https://github.com/openfoodfacts/openfoodfacts-server/issues/7944
- [ ] OpenAPI: document getting a specific nutrient field #7944

#### Developer journeys
- [ ] #7872
- [ ] #7873
- [ ] #7874
- [ ] #7875
- [ ] #7876
- [ ] #7877

#### Link to other API documentations
- [ ] #7745
- [ ] #7746
- [ ] #7747
- [ ] #7748
- [ ] https://github.com/openfoodfacts/openfoodfacts-server/issues/10205
- [ ] https://github.com/openfoodfacts/openfoodfacts-server/issues/10206
- [ ] Create a quick pointer to the Nutri-Patrol API in the doc : https://nutripatrol.openfoodfacts.org/api/docs

### Link to other useful documents
- [ ] Add a link to the Producer documentation
- [ ] Add a link to the Nutri-Score documentation
- [ ] Add a link to the Eco-Score documentation
- [ ] Add a link to the NOVA documentation
- [ ] Add a link to the Product GET API
- [ ] Add a link to  the Nutrition facts  GET API
- [ ] Add a link to the Tags GET API
- [ ] Add a link to the Attributes GET API
- [x] Add a link to the Knowledge Panels GET API

#### Fix bugs

#### Simplify, clarify and fix the existing documentation
- [ ] Fix the image upload explanations

### Document new APIs
- [ ] https://github.com/openfoodfacts/openfoodfacts-server/issues/10180 
- [ ] https://github.com/openfoodfacts/api-documentation/issues/17 
- [ ] https://github.com/openfoodfacts/openfoodfacts-server/issues/10183 
- [x] https://github.com/openfoodfacts/api-documentation/issues/19 
- [ ] Transfer https://github.com/openfoodfacts/api-documentation/issues/19 to OpenAPI
- [x] https://github.com/openfoodfacts/api-documentation/issues/9 
- [ ] Transfer https://github.com/openfoodfacts/api-documentation/issues/9  to OpenAPI
- [ ] https://github.com/openfoodfacts/api-documentation/issues/10 
- [ ] https://github.com/openfoodfacts/openfoodfacts-server/issues/10187 
- [ ] https://github.com/openfoodfacts/api-documentation/issues/71 
- [ ] https://github.com/openfoodfacts/api-documentation/issues/70 
- [ ] https://github.com/openfoodfacts/api-documentation/issues/68 
- [ ] https://github.com/openfoodfacts/api-documentation/issues/66 
- [ ] https://github.com/openfoodfacts/api-documentation/issues/62 
- [ ] https://github.com/openfoodfacts/api-documentation/issues/61 
- [ ] https://github.com/openfoodfacts/api-documentation/issues/49
- [ ] https://github.com/openfoodfacts/api-documentation/issues/37

#### Create API use cases
- [x] https://github.com/openfoodfacts/api-documentation/issues/6 
  - [ ] Transfer https://github.com/openfoodfacts/api-documentation/issues/6  to OpenAPI
- [ ] https://github.com/openfoodfacts/api-documentation/issues/21

#### Document and valorize the SDKs within the doc
- [ ] https://github.com/openfoodfacts/openfoodfacts-server/issues/10179

#### Disseminate the doc
- [x] https://github.com/openfoodfacts/api-documentation/issues/8 
  - [x] Transfer https://github.com/openfoodfacts/api-documentation/issues/8 to OpenAPI

#### Auto-generate SDKs from the OpenAPI documentation 
- [x] #7884
- [ ] #7885

### To be sorted
- [ ] https://github.com/openfoodfacts/openfoodfacts-server/issues/10184 
- [ ] https://github.com/openfoodfacts/api-documentation/issues/12 
- [ ] https://github.com/openfoodfacts/api-documentation/issues/13 
- [ ] https://github.com/openfoodfacts/api-documentation/issues/20 
- [ ] https://github.com/openfoodfacts/api-documentation/issues/22

### Done
- [x] https://github.com/openfoodfacts/api-documentation/issues/1 
- [x] https://github.com/openfoodfacts/api-documentation/issues/2 
- [x] https://github.com/openfoodfacts/api-documentation/issues/3

Why

The better the documentation, the easier it is to use the API, the better Open Food Facts can fulfill its mission

Part of

5529

teolemon commented 1 year ago

cc @stephanegigandet @Roxie-32 @alexgarel Documentation issue tracking

github-actions[bot] commented 9 months ago

This issue has been open 90 days with no activity. Can you give it a little love by linking it to a parent issue, adding relevant labels and projets, creating a mockup if applicable, adding code pointers from https://github.com/openfoodfacts/openfoodfacts-server/blob/main/.github/labeler.yml, giving it a priority, editing the original issue to have a more comprehensive description… Thank you very much for your contribution to 🍊 Open Food Facts

openfoodfacts / openfoodfacts-server