docs: cleaning and dispatching product schema (#8672)

* improves a lot the product schema * fix rendering with rapidoc (by having a correct schema) * split the product schema into coherent and readable parts, and expose them * restores the OpenAPI check with swagger * put big example in its own file
openfoodfacts · Jul 25, 2023 · 39560c8 · 39560c8
1 parent b2d58e3
commit 39560c8
Show file tree

Hide file tree

Showing 29 changed files with 2,655 additions and 3,270 deletions.
diff --git a/.github/workflows/generate-doc.yml b/.github/workflows/generate-doc.yml
@@ -62,15 +62,9 @@ jobs:
       #       build -o /output/api/ref-v3/index.html api-v3.yml && \
       #     sudo chown $UID -R gh_pages
 
-      # Disabled by alex on 2023-03-09 because of a false positive Error:
-      # "attribute .Product. is not of type `object` (../schemas/product.yaml#/Product)"
-      # because of legit `$ref: ../schemas/product.yaml#/Product` in `get_product_by_barcode.yaml`
-      #
-      # - name: Validate OpenAPI
-      #   run: |
-      #     docker run --rm \
-      #     -v ${PWD}:/local openapitools/openapi-generator-cli validate \
-      #     -i /local/docs/reference/api.yml \
+      - name: Validate OpenAPI
+        run: |
+          make check_openapi
 
       # generate OpenAPI documentation with rapidoc
       # we do this after mkdocs to overwrite api.html file

diff --git a/Makefile b/Makefile
@@ -340,6 +340,19 @@ check_critic:
 	@echo "🥫 Checking with perlcritic"
 	test -z "${TO_CHECK}" || ${DOCKER_COMPOSE} run --rm --no-deps backend perlcritic ${TO_CHECK}
 
+
+check_openapi_v2:
+	docker run --rm \
+		-v ${PWD}:/local openapitools/openapi-generator-cli validate --recommend \
+		-i /local/docs/api/ref/api.yml
+
+check_openapi_v3:
+	docker run --rm \
+		-v ${PWD}:/local openapitools/openapi-generator-cli validate --recommend \
+		-i /local/docs/api/ref/api-v3.yml
+
+check_openapi: check_openapi_v2 check_openapi_v3
+
 #-------------#
 # Compilation #
 #-------------#

diff --git a/docs/api/ref/api-v3.yml b/docs/api/ref/api-v3.yml
@@ -304,9 +304,6 @@ paths:
           in: query
           name: term
           description: Alias for the "string" parameter provided for backward compatibility. "string" takes precedence.
-components:
-  schemas: null
-  parameters: null
 tags:
   - name: Read Requests
   - name: Write Requests
diff --git a/docs/api/ref/api.yml b/docs/api/ref/api.yml
@@ -13,8 +13,13 @@ info:
   license:
     name: 'data: ODbL'
     url: 'https://opendatacommons.org/licenses/odbl/summary/index.html'
-    identifier: "ODbL-1.0"
+    # can't use url and identifier - use x-identifier
+    x-identifier: "ODbL-1.0"
   version: '2'
+externalDocs:
+  description: |
+    Please read the API introduction before using this API.
+  url: https://openfoodfacts.github.io/openfoodfacts-server/api/
 servers:
   - description: dev
     url: 'https://world.openfoodfacts.net'
@@ -44,6 +49,10 @@ paths:
             application/json:
               schema:
                 $ref: ./responses/get_product_by_barcode.yaml
+              examples:
+                spread-example:
+                  $ref: ./examples/get_product_by_barcode_spread.yaml
+
       description: |
         A product can be fetched via its unique barcode.
         It returns all the details of that product response.
@@ -77,10 +86,7 @@ paths:
                   - type: object
                     properties:
                       product:
-                        type: object
-                        properties:
-                          knowledge_panels:
-                            $ref: ./schemas/knowledge_panels/panels.yaml
+                        $ref: ./schemas/product_knowledge_panels.yaml
       description: |
         Knowledge panels gives high leve informations about a product,
         ready to display.
@@ -152,6 +158,7 @@ paths:
           multipart/form-data:
             schema:
               $ref: ./requestBodies/crop_a_photo.yaml
+        required: true
       tags:
         - Write Requests
     get:
@@ -288,48 +295,28 @@ paths:
         all packaging_shapes containing "fe" will be returned.
         This is useful if you have a search in your application,
         for a specific product field.
-  '/api/v2/product/{barcode}?fields=images':
-    parameters:
-      - schema:
-          type: string
-        name: barcode
-        in: path
-        required: true
-    get:
-      summary: Get Images for a specific product by barcode (special case of get product)
-      tags:
-        - Read Requests
-      responses:
-        '200':
-          description: OK
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  code:
-                    type: string
-                    example: '3017620422003'
-                  product:
-                    type: object
-                    properties:
-                      images:
-                        type: object
-                        patternProperties:
-                          /^\d+$/:
-                            $ref: ./schemas/images/image.yaml
-                          (front|ingredients|nutrition|packaging|other)_\w\w(-\w\w)?:
-                            $ref: ./schemas/images/selected_image.yaml
-                  status:
-                    type: integer
-                    example: 1
-                  status_verbose:
-                    type: string
-                    example: product found
-      operationId: get-api-v2-product-barcode-?fields=images
-      description: Images ensure the reliability of Open Food Facts data. It provides a primary source and proof of all the structured data. You may therefore want to display it along the structured information.
 components:
   schemas:
+    "Product-Base":
+      $ref: ./schemas/product_base.yaml
+    "Product-Misc":
+      $ref: ./schemas/product_misc.yaml
+    "Product-Tags":
+      $ref: ./schemas/product_tags.yaml
+    "Product-Nutrition":
+      $ref: ./schemas/product_nutrition.yaml
+    "Product-Ingredients":
+      $ref: ./schemas/product_ingredients.yaml
+    "Product-Images":
+      $ref: ./schemas/product_images.yaml
+    "Product-Eco-Score":
+      $ref: ./schemas/product_ecoscore.yaml
+    "Product-Metadata":
+      $ref: ./schemas/product_meta.yaml
+    "Product-Data-Quality":
+      $ref: ./schemas/product_quality.yaml
+    "Product-Knowledge-Panels":
+      $ref: ./schemas/product_knowledge_panels.yaml
     Product:
       $ref: ./schemas/product.yaml
   parameters: