From ff2aa7717159e04d0cc8fe75ef8292468a4f97eb Mon Sep 17 00:00:00 2001
From: Marc Wrobel <marc.wrobel@gmail.com>
Date: Sun, 22 Jan 2023 20:28:05 +0100
Subject: [PATCH] Add schema_version (#2331)

---
 _plugins/generate-api-v1.rb | 35 ++++++++++++++++++++++++-----------
 api_v1/openapi.yml          | 16 ++++++++++++++++
 2 files changed, 40 insertions(+), 11 deletions(-)

diff --git a/_plugins/generate-api-v1.rb b/_plugins/generate-api-v1.rb
index 6a7543eae4f..8364d8bb117 100755
--- a/_plugins/generate-api-v1.rb
+++ b/_plugins/generate-api-v1.rb
@@ -1,13 +1,25 @@
 # This script creates API files for version 1 of the endoflife.date API.
 #
-# There are two kind of generated files :
-# - all.json: contains endoflife metadata, such as the list of all the products and the product count.
-# - <product>.json: contains a given product data (including releases data).
+# There are multiples endpoints :
+#
+# - /api/v1/ - list all major endpoints (those not requiring a parameter)
+# - /api/v1/products/ - list all products
+# - /api/v1/products/<product>/ - get a single product details
+# - /api/v1/products/<product>/latest - get details on the latest cycle for the given product
+# - /api/v1/products/<product>/<cycle> - get details on the given cycle for the given product
+# - /api/v1/categories/ - list categories used on endoflife.date
+# - /api/v1/categories/<category> - list products having the given category
+# - /api/v1/tags/ - list tags used on endoflife.date
+# - /api/v1/tags/<tag> - list products having the given tag
+
 
 require 'jekyll'
 
 module ApiV1
 
+  VERSION = '1.0.0-b1'
+  MAJOR_VERSION = VERSION.split('.')[0]
+
   STRIP_HTML_BLOCKS = Regexp.union(
     /<script.*?<\/script>/m,
     /<!--.*?-->/m,
@@ -29,7 +41,7 @@ class ApiGenerator < Jekyll::Generator
     safe true
     priority :lowest
 
-    TOPIC = "API v1:"
+    TOPIC = "API " + ApiV1::VERSION + ":"
 
     def generate(site)
       @site = site
@@ -53,9 +65,9 @@ def add_index_page(site)
       site_url = site.config['url']
       site.pages << JsonPage.new(site, '/', 'index', {
         result: [
-          { name: "products", uri: "#{site_url}/api/v1/products/" },
-          { name: "categories", uri: "#{site_url}/api/v1/categories/" },
-          { name: "tags", uri: "#{site_url}/api/v1/tags/" },
+          { name: "products", uri: "#{site_url}/api/v#{ApiV1::MAJOR_VERSION}/products/" },
+          { name: "categories", uri: "#{site_url}/api/v#{ApiV1::MAJOR_VERSION}/categories/" },
+          { name: "tags", uri: "#{site_url}/api/v#{ApiV1::MAJOR_VERSION}/tags/" },
         ]
       })
     end
@@ -101,7 +113,7 @@ def add_all_categories_page(site, products)
                   .map { |product| product.data['category'] }
                   .uniq
                   .sort
-                  .map { |category| { name: category, uri: "#{site.config['url']}/api/v1/categories/#{category}/" } }
+                  .map { |category| { name: category, uri: "#{site.config['url']}/api/v#{ApiV1::MAJOR_VERSION}/categories/#{category}/" } }
       })
     end
 
@@ -123,7 +135,7 @@ def add_all_tags_page(site, products)
                   .flat_map { |product| product.data['tags'] }
                   .uniq
                   .sort
-                  .map { |tag| { name: tag, uri: "#{site.config['url']}/api/v1/tags/#{tag}/" } }
+                  .map { |tag| { name: tag, uri: "#{site.config['url']}/api/v#{ApiV1::MAJOR_VERSION}/tags/#{tag}/" } }
       })
     end
 
@@ -140,11 +152,12 @@ class JsonPage < Jekyll::Page
     def initialize(site, path, name, data)
       @site = site
       @base = site.source
-      @dir = "api/v1#{path}"
+      @dir = "api/v#{ApiV1::MAJOR_VERSION}#{path}"
       @name = "#{name}.json"
       @data = {}
       @data['layout'] = 'json'
       @data['data'] = data
+      @data['data']['schema_version'] = ApiV1::VERSION
 
       self.process(@name)
     end
@@ -159,7 +172,7 @@ def initialize(site, path, name, products)
           label: product.data['title'],
           category: product.data['category'],
           tags: product.data['tags'],
-          uri: "#{site.config['url']}/api/v1/products/#{product.data['id']}/",
+          uri: "#{site.config['url']}/api/v#{ApiV1::MAJOR_VERSION}/products/#{product.data['id']}/",
         } }
       })
     end
diff --git a/api_v1/openapi.yml b/api_v1/openapi.yml
index 8f4d493872d..a8897414e87 100644
--- a/api_v1/openapi.yml
+++ b/api_v1/openapi.yml
@@ -200,6 +200,10 @@ components:
     UriList:
       type: object
       properties:
+        schema_version:
+          type: string
+          description: Version of this schema.
+          example: 1.0.0
         result:
           type: array
           items:
@@ -234,6 +238,10 @@ components:
     ProductList:
       type: object
       properties:
+        schema_version:
+          type: string
+          description: Version of this schema.
+          example: 1.0.0
         total:
           type: integer
           format: int32
@@ -265,6 +273,10 @@ components:
     ProductCycle:
       type: object
       properties:
+        schema_version:
+          type: string
+          description: Version of this schema.
+          example: 1.0.0
         name:
           type: string
           description: Name of the product cycle.
@@ -329,6 +341,10 @@ components:
     Product:
       type: object
       properties:
+        schema_version:
+          type: string
+          description: Version of this schema.
+          example: 1.0.0
         name:
           type: string
           description: Name of the product.