Api rework

CHANGELOG.md

@@ -23,13 +23,15 @@
   [#1442](https://github.com/nextcloud/cookbook/pull/1442) @christianlupus
 
 ## Documentation
-- Fixed some issues in the API description
+- Fixed some issues in the API description #1419 and #1461 @leptopoda
+- Improve API description for better code-generation #1461 @leptopoda
 - Fix security issue in GitHub pages with path insertion
   [#1457](https://github.com/nextcloud/cookbook/pull/1457) @christianlupus
 - Add quick start guide for backend testing
   [#1466](https://github.com/nextcloud/cookbook/pull/1466) @MarcelRobitaille
 - Fixed some typos in the OpenAPI specification @leptopoda
 - Add operation ids to all external API endpoints
+- Improve API description for better code-generation #1461 @leptopoda
 
 
 ## 0.10.1 - 2022-11-09

docs/dev/api/0.1.0/objects.yaml

@@ -110,10 +110,6 @@ Instruction:
 Nutrition:
   type: object
   properties:
-    "@type":
-      type: string
-      example: NutritionInformation
-      description: Schema.org object description
     calories:
       type: string
       description: The number of calories for the given amount
@@ -162,8 +158,6 @@ Nutrition:
       type: string
       description: The number of grams of unsaturated fat
       example: 40 g
-  required:
-    - "@type"
 
 Recipe:
   #type: object
@@ -172,10 +166,6 @@ Recipe:
     - $ref: "#/RecipeStubInformation"
     - type: object
       properties:
-        "@type":
-          type: string
-          example: "Recipe"
-          description: Schema.org object type identifier
         id:
           type: string
           description: The index of the recipe. Note the representation as a string as the representation might change in the future.

docs/dev/api/0.1.1/objects.yaml

@@ -1,3 +1,29 @@
+Category:
+  type: object
+  description: A category
+  allOf:
+    - $ref: "#/CategoryInformation"
+
+CategoryInformation:
+  type: object
+  description: >-
+    The very basic information of a category
+
+    Please note: A category name of `*` indicates the number of
+    recipes with no category associated.
+  properties:
+    name:
+      type: string
+      description: The name of the category
+      example: Dinner
+    recipe_count:
+      type: integer
+      description: The number of recipes in the category
+      example: 21
+  required:
+    - name
+    - recipe_count
+
 Config:
   type: object
   description: An object describing the configuration of the web app
@@ -6,14 +32,17 @@ Config:
       type: string
       example: /Recipes
       description: The folder in the user's files that contains the recipes
+      nullable: true
     update_interval:
       type: integer
       example: 10
       description: The interval between automatic rescans to rebuild the database cache in minutes
+      nullable: true
     print_image:
       type: boolean
       example: true
       description: True, if the user wished to print the recipe images with the rest of the recipes
+      nullable: true
   required:
     - folder
     - update_interval
@@ -36,6 +65,12 @@ Error:
       description: The line where the exception is thrown
       example: 223
 
+Keyword:
+  type: object
+  description: An Keyword
+  allOf:
+    - $ref: "#/CategoryInformation"
+
 RecipeStubInformation:
   type: object
   description: The very basic information of a recipe
@@ -48,6 +83,7 @@ RecipeStubInformation:
       type: string
       description: A comma-separated list of recipe keywords, can be empty string
       example: sweets,fruit
+      default: ""
     dateCreated:
       type: string
       description: The date the recipe was created in the app
@@ -62,10 +98,12 @@ RecipeStubInformation:
       type: string
       description: The URL of the recipe image
       example: http://example.com/path/to/image.jpg
+      default: ""
     imagePlaceholderUrl:
       type: string
       description: The URL of the placeholder of the recipe image
       example: http://example.com/path/to/image_thumb.jpg
+      default: ""
   required:
     - "name"
     - "keywords"
@@ -110,10 +148,6 @@ Instruction:
 Nutrition:
   type: object
   properties:
-    "@type":
-      type: string
-      example: NutritionInformation
-      description: Schema.org object description
     calories:
       type: string
       description: The number of calories for the given amount
@@ -162,8 +196,6 @@ Nutrition:
       type: string
       description: The number of grams of unsaturated fat
       example: 40 g
-  required:
-    - "@type"
 
 Recipe:
   #type: object
@@ -172,14 +204,11 @@ Recipe:
     - $ref: "#/RecipeStubInformation"
     - type: object
       properties:
-        "@type":
-          type: string
-          example: "Recipe"
-          description: Schema.org object type identifier
         id:
           type: string
           description: The index of the recipe. Note the representation as a string as the representation might change in the future.
           example: "123"
+          nullable: true
         prepTime:
           type: string
           nullable: true
@@ -199,22 +228,27 @@ Recipe:
           type: string
           example: A very easy way to make children happy
           description: A description of the recipe or the empty string
+          default: ""
         url:
           type: string
           example: http://exmaple.com/my-recipe.html
           description: The URL the recipe was found at or the empty string
+          default: ""
         image:
           type: string
           example: http://example.com/my-recipe-image.jpeg
           description: The URL of the original recipe
+          default: ""
         recipeYield:
           type: integer
           example: 4
           description: Number of servings in recipe
+          default: 1
         recipeCategory:
           type: string
           example: Dessert
           description: The category of the recipe
+          default: ""
         tool:
           type: array
           items:
@@ -253,7 +287,7 @@ Recipe:
     prepTime: PT0H15M
     cookTime: null
     totalTime: PT1H20M
-    url: ''
+    url: ""
     tool: []
     recipeIngredient:
       - 3 ripe bananas
@@ -382,6 +416,15 @@ APIVersion:
     major: 1
     minor: 3
 
+Url:
+  type: object
+  properties:
+    url:
+      type: string
+      example: "http://www.chefkoch.de/2345"
+  required:
+    - url
+
 Version:
   type: object
   properties:

docs/dev/api/0.1.1/openapi-cookbook.yaml

@@ -63,16 +63,22 @@ tags:
 
 components:
   schemas:
+    Category:
+      $ref: objects.yaml#/Category
     Config:
       $ref: objects.yaml#/Config
     Error:
       $ref: objects.yaml#/Error
+    Keyword:
+      $ref: objects.yaml#/Keyword
     RecipeStub:
       $ref: objects.yaml#/RecipeStub
     StubList:
       $ref: objects.yaml#/StubList
     Recipe:
       $ref: objects.yaml#/Recipe
+    Url:
+      $ref: objects.yaml#/Url
     Version:
       $ref: objects.yaml#/Version
 
@@ -128,6 +134,12 @@ paths:
       tags: [ Misc ]
       summary: Set the configuration for the current user
       operationId: setConfig
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/Config"
       responses:
         200:
           description: The configuration was successfully saved.
@@ -143,16 +155,12 @@ paths:
       summary: Import a recipe using schema.org metadata from a website
       operationId: import
       requestBody:
+        required: true
         content:
           application/json:
             schema:
-              type: object
-              properties:
-                url:
-                  type: string
-                  example: 'http://www.chefkoch.de/2345'
-              required:
-                - url
+              $ref: "#/components/schemas/Url"
+
       responses:
         200:
           description: Successfully imported recipe
@@ -185,6 +193,20 @@ paths:
           required: true
           schema:
             type: integer
+        - in: query
+          name: size
+          description: >
+            The size of the requested image
+
+            * `full`    - Full resolution image (size full res)
+            * `thumb`   - thumbnail of the image (size 250px)
+            * `thumb16` - icon of the image (size 16px)
+
+            by default the full size image will be returned
+          required: false
+          schema:
+            type: string
+            enum: [full, thumb, thumb16]
       responses:
         200:
           description: Image was obtained and will be in response either as image/jpeg or image/svg+xml
@@ -246,15 +268,11 @@ paths:
           A JSON representation of the recipe to be saved.
 
           See also the structure at https://schema.org/Recipe
+        required: true
         content:
           application/json:
             schema:
-              type: object
-              properties:
-                name:
-                  type: string
-              required: [ "name" ]
-              additionalProperties: true
+              $ref: "#/components/schemas/Recipe"
               example:
                 name: "Chips"
                 description: "A very delicious way of getting kids quiet"
@@ -317,6 +335,7 @@ paths:
       summary: Update a recipe
       operationId: updateRecipe
       requestBody:
+        required: true
         content:
           application/json:
             schema:
@@ -371,20 +390,8 @@ paths:
               schema:
                 type: array
                 items:
-                  type: object
-                  properties:
-                    name:
-                      type: string
-                    recipe_count:
-                      type: integer
-                  required:
-                    - name
-                    - recipe_count
-              example:
-                - name: vegetarian
-                  recipe_count: 5
-                - name: sugar-free
-                  recipe_count: 2
+                  $ref: "#/components/schemas/Keyword"
+
   /api/v1/tags/{keywords}:
     get:
       tags: [ Tags ]
@@ -431,15 +438,7 @@ paths:
               schema:
                 type: array
                 items:
-                  type: object
-                  properties:
-                    name:
-                      type: string
-                    recipe_count:
-                      type: integer
-                  required:
-                    - name
-                    - recipe_count
+                  $ref: "#/components/schemas/Category"
               example:
                 - name: Dinner
                   recipe_count: 21
@@ -494,6 +493,7 @@ paths:
           schema:
             type: string
       requestBody:
+        required: true
         content:
           application/json:
             schema:

docs/dev/api/changelog/0.md

@@ -14,7 +14,7 @@ Only the endpoints under `/webapp/` or `/api/v1/` are working in the future.
 See also [the section](#split-and-rename-api-endpoints).
 
 ### Fix OpenAPI format specification
-There were some minor flaws in the spec file.
+There were some minor flaws and typos in the spec file.
 These flaws caused some code generation tools to fail or produce incomplete results.
 
 The fixture of these issues should not be critical as these are mainly cosmetic and will __not__ change the actual transmitted data.