Export OpenAPI definitions from service examples; affects [dynamic endpoint static] (#8966)

* WIP export OpenAPI definitions from service examples

* allow services to optionally define an OpenApi Paths Object instead of examples

* make use of param descriptions and required query params

* convert other 'core' services to declare openApi..

..instead of examples

* tweak descriptions for standard query params

* move stuff around, add a high-level integration test for category2openapi

* update simple-icons text refs #9054

* remove legacy param names

scripts/export-openapi-cli.js

@@ -0,0 +1,49 @@
+import fs from 'fs'
+import path from 'path'
+import yaml from 'js-yaml'
+import { collectDefinitions } from '../core/base-service/loader.js'
+import { category2openapi } from '../core/base-service/openapi.js'
+
+const specsPath = path.join('frontend', 'categories')
+
+function writeSpec(filename, spec) {
+  // Omit undefined
+  // https://github.com/nodeca/js-yaml/issues/356#issuecomment-312430599
+  const cleaned = JSON.parse(JSON.stringify(spec))
+
+  fs.writeFileSync(
+    filename,
+    yaml.dump(cleaned, { flowLevel: 5, forceQuotes: true })
+  )
+}
+
+;(async () => {
+  const definitions = await collectDefinitions()
+
+  for (const category of definitions.categories) {
+    const services = definitions.services.filter(
+      service => service.category === category.id && !service.isDeprecated
+    )
+
+    writeSpec(
+      path.join(specsPath, `${category.id}.yaml`),
+      category2openapi(category, services)
+    )
+  }
+
+  let coreServices = []
+  coreServices = coreServices.concat(
+    definitions.services.filter(
+      service => service.category === 'static' && !service.isDeprecated
+    )
+  )
+  coreServices = coreServices.concat(
+    definitions.services.filter(
+      service => service.category === 'dynamic' && !service.isDeprecated
+    )
+  )
+  writeSpec(
+    path.join(specsPath, '1core.yaml'),
+    category2openapi({ name: 'Core' }, coreServices)
+  )
+})()

scripts/export-service-definitions-cli.js

@@ -3,6 +3,19 @@ import { collectDefinitions } from '../core/base-service/loader.js'
 ;(async () => {
   const definitions = await collectDefinitions()
 
+  // filter out static, dynamic and debug badge examples
+  const publicCategories = definitions.categories.map(c => c.id)
+  definitions.services = definitions.services.filter(s =>
+    publicCategories.includes(s.category)
+  )
+
+  // drop the openApi property for the "legacy" frontend
+  for (const service of definitions.services) {
+    if (service.openApi) {
+      service.openApi = undefined
+    }
+  }
+
   // Omit undefined
   // https://github.com/nodeca/js-yaml/issues/356#issuecomment-312430599
   const cleaned = JSON.parse(JSON.stringify(definitions))