From e9c3f7ee1cb186f68d5c42add0552e4487d8b792 Mon Sep 17 00:00:00 2001 From: Flam3rboy <34555296+Flam3rboy@users.noreply.github.com> Date: Tue, 21 Sep 2021 23:29:17 +0200 Subject: :sparkles: example value in documentation --- api/package.json | 5 +- api/scripts/generate_body_schema.js | 70 ----------------- api/scripts/generate_openapi.js | 137 +++++++++++++++++++++++++++++++++ api/scripts/generate_openapi_schema.js | 127 ------------------------------ api/scripts/generate_schema.js | 70 +++++++++++++++++ 5 files changed, 209 insertions(+), 200 deletions(-) delete mode 100644 api/scripts/generate_body_schema.js create mode 100644 api/scripts/generate_openapi.js delete mode 100644 api/scripts/generate_openapi_schema.js create mode 100644 api/scripts/generate_schema.js (limited to 'api') diff --git a/api/package.json b/api/package.json index 53031071..a1d3b5b2 100644 --- a/api/package.json +++ b/api/package.json @@ -15,9 +15,8 @@ "dev": "tsnd --respawn src/start.ts", "patch": "npx patch-package", "postinstall": "npm run patch", - "generate:docs": "ts-node scripts/generate_openapi_schema.ts", - "generate:test": "ts-node scripts/generate_test_schema.ts", - "generate:schema": "ts-node scripts/generate_body_schema.ts" + "generate:docs": "node scripts/generate_openapi.ts", + "generate:schema": "node scripts/generate_schema.ts" }, "repository": { "type": "git", diff --git a/api/scripts/generate_body_schema.js b/api/scripts/generate_body_schema.js deleted file mode 100644 index 22d0b02e..00000000 --- a/api/scripts/generate_body_schema.js +++ /dev/null @@ -1,70 +0,0 @@ -// https://mermade.github.io/openapi-gui/# -// https://editor.swagger.io/ -import path from "path"; -import fs from "fs"; -import * as TJS from "typescript-json-schema"; -import "missing-native-js-functions"; -const schemaPath = path.join(__dirname, "..", "assets", "schemas.json"); - -const settings = { - required: true, - ignoreErrors: true, - excludePrivate: true, - defaultNumberType: "integer", - noExtraProps: true, - defaultProps: false -}; -const compilerOptions = { - strictNullChecks: true -}; -const Excluded = [ - "DefaultSchema", - "Schema", - "EntitySchema", - "ServerResponse", - "Http2ServerResponse", - "global.Express.Response", - "Response", - "e.Response", - "request.Response", - "supertest.Response" -]; - -function main() { - const program = TJS.getProgramFromFiles(walk(path.join(__dirname, "..", "src", "routes")), compilerOptions); - const generator = TJS.buildGenerator(program, settings); - if (!generator || !program) return; - - const schemas = generator.getUserSymbols().filter((x) => (x.endsWith("Schema") || x.endsWith("Response")) && !Excluded.includes(x)); - console.log(schemas); - - var definitions = {}; - - for (const name of schemas) { - const part = TJS.generateSchema(program, name, settings, [], generator); - if (!part) continue; - - definitions = { ...definitions, [name]: { ...part } }; - } - - fs.writeFileSync(schemaPath, JSON.stringify(definitions, null, 4)); -} - -main(); - -function walk(dir) { - var results = []; - var list = fs.readdirSync(dir); - list.forEach(function (file) { - file = dir + "/" + file; - var stat = fs.statSync(file); - if (stat && stat.isDirectory()) { - /* Recurse into a subdirectory */ - results = results.concat(walk(file)); - } else { - if (!file.endsWith(".ts")) return; - results.push(file); - } - }); - return results; -} diff --git a/api/scripts/generate_openapi.js b/api/scripts/generate_openapi.js new file mode 100644 index 00000000..c9de9fa6 --- /dev/null +++ b/api/scripts/generate_openapi.js @@ -0,0 +1,137 @@ +// https://mermade.github.io/openapi-gui/# +// https://editor.swagger.io/ +const getRouteDescriptions = require("../jest/getRouteDescriptions"); +const path = require("path"); +const fs = require("fs"); +require("missing-native-js-functions"); + +const openapiPath = path.join(__dirname, "..", "assets", "openapi.json"); +const SchemaPath = path.join(__dirname, "..", "assets", "schemas.json"); +const schemas = JSON.parse(fs.readFileSync(SchemaPath, { encoding: "utf8" })); +const specification = JSON.parse(fs.readFileSync(openapiPath, { encoding: "utf8" })); + +function combineSchemas(schemas) { + var definitions = {}; + + for (const name in schemas) { + definitions = { + ...definitions, + ...schemas[name].definitions, + [name]: { ...schemas[name], definitions: undefined, $schema: undefined } + }; + } + + for (const key in definitions) { + specification.components.schemas[key] = definitions[key]; + delete definitions[key].additionalProperties; + delete definitions[key].$schema; + const definition = definitions[key]; + + if (typeof definition.properties === "object") { + for (const property of Object.values(definition.properties)) { + if (Array.isArray(property.type)) { + if (property.type.includes("null")) { + property.type = property.type.find((x) => x !== "null"); + property.nullable = true; + } + } + } + } + } + + return definitions; +} + +function getTag(key) { + return key.match(/\/([\w-]+)/)[1]; +} + +function apiRoutes() { + const routes = getRouteDescriptions(); + + const tags = Array.from(routes.keys()).map((x) => getTag(x)); + specification.tags = [...specification.tags.map((x) => x.name), ...tags].unique().map((x) => ({ name: x })); + + routes.forEach((route, pathAndMethod) => { + const [p, method] = pathAndMethod.split("|"); + const path = p.replace(/:(\w+)/g, "{$1}"); + + let obj = specification.paths[path]?.[method] || {}; + if (!obj.description) { + const permission = route.permission ? `##### Requires the \`\`${route.permission}\`\` permission\n` : ""; + const event = route.test?.event ? `##### Fires a \`\`${route.test?.event}\`\` event\n` : ""; + obj.description = permission + event; + } + if (route.body) { + obj.requestBody = { + required: true, + content: { + "application/json": { + schema: { $ref: `#/components/schemas/${route.body}` } + } + } + }.merge(obj.requestBody); + } + if (!obj.responses) { + obj.responses = { + default: { + description: "not documented" + } + }; + } + if (route.test?.response) { + const status = route.test.response.status || 200; + let schema = { + allOf: [ + { + $ref: `#/components/schemas/${route.test.response.body}` + }, + { + example: route.test.body + } + ] + }; + if (!route.test.body) schema = schema.allOf[0]; + + obj.responses = { + [status]: { + ...(route.test.response.body + ? { + description: obj.responses[status].description || "", + content: { + "application/json": { + schema: schema + } + } + } + : {}) + } + }.merge(obj.responses); + delete obj.responses.default; + } + if (p.includes(":")) { + obj.parameters = p.match(/:\w+/g)?.map((x) => ({ + name: x.replace(":", ""), + in: "path", + required: true, + schema: { type: "string" }, + description: x.replace(":", "") + })); + } + obj.tags = [...(obj.tags || []), getTag(p)].unique(); + + specification.paths[path] = { ...specification.paths[path], [method]: obj }; + }); +} + +function main() { + combineSchemas(schemas); + apiRoutes(); + + fs.writeFileSync( + openapiPath, + JSON.stringify(specification, null, 4).replaceAll("#/definitions", "#/components/schemas").replaceAll("bigint", "number") + ); +} + +main(); diff --git a/api/scripts/generate_openapi_schema.js b/api/scripts/generate_openapi_schema.js deleted file mode 100644 index eb979f14..00000000 --- a/api/scripts/generate_openapi_schema.js +++ /dev/null @@ -1,127 +0,0 @@ -// https://mermade.github.io/openapi-gui/# -// https://editor.swagger.io/ -const getRouteDescriptions = require("../jest/getRouteDescriptions"); -const path = require("path"); -const fs = require("fs"); -require("missing-native-js-functions"); - -const openapiPath = path.join(__dirname, "..", "assets", "openapi.json"); -const SchemaPath = path.join(__dirname, "..", "assets", "schemas.json"); -const schemas = JSON.parse(fs.readFileSync(SchemaPath, { encoding: "utf8" })); -const specification = JSON.parse(fs.readFileSync(openapiPath, { encoding: "utf8" })); - -function combineSchemas(schemas) { - var definitions = {}; - - for (const name in schemas) { - definitions = { - ...definitions, - ...schemas[name].definitions, - [name]: { ...schemas[name], definitions: undefined, $schema: undefined } - }; - } - - for (const key in definitions) { - specification.components.schemas[key] = definitions[key]; - delete definitions[key].additionalProperties; - delete definitions[key].$schema; - const definition = definitions[key]; - - if (typeof definition.properties === "object") { - for (const property of Object.values(definition.properties)) { - if (Array.isArray(property.type)) { - if (property.type.includes("null")) { - property.type = property.type.find((x) => x !== "null"); - property.nullable = true; - } - } - } - } - } - - return definitions; -} - -function getTag(key) { - return key.match(/\/([\w-]+)/)[1]; -} - -function apiRoutes() { - const routes = getRouteDescriptions(); - - const tags = Array.from(routes.keys()).map((x) => getTag(x)); - specification.tags = [...specification.tags.map((x) => x.name), ...tags].unique().map((x) => ({ name: x })); - - routes.forEach((route, pathAndMethod) => { - const [p, method] = pathAndMethod.split("|"); - const path = p.replace(/:(\w+)/g, "{$1}"); - - let obj = specification.paths[path]?.[method] || {}; - if (!obj.description) { - const permission = route.permission ? `##### Requires the \`\`${route.permission}\`\` permission\n` : ""; - const event = route.test?.event ? `##### Fires a \`\`${route.test?.event}\`\` event\n` : ""; - obj.description = permission + event; - } - if (route.body) { - obj.requestBody = { - required: true, - content: { - "application/json": { - schema: { $ref: `#/components/schemas/${route.body}` } - } - } - }.merge(obj.requestBody); - } - if (!obj.responses) { - obj.responses = { - default: { - description: "not documented" - } - }; - } - if (route.test?.response) { - const status = route.test.response.status || 200; - obj.responses = { - [status]: { - ...(route.test.response.body - ? { - description: obj.responses[status].description || "", - content: { - "application/json": { - schema: { - $ref: `#/components/schemas/${route.test.response.body}` - } - } - } - } - : {}) - } - }.merge(obj.responses); - delete obj.responses.default; - } - if (p.includes(":")) { - obj.parameters = p.match(/:\w+/g)?.map((x) => ({ - name: x.replace(":", ""), - in: "path", - required: true, - schema: { type: "string" }, - description: x.replace(":", "") - })); - } - obj.tags = [...(obj.tags || []), getTag(p)].unique(); - - specification.paths[path] = { ...specification.paths[path], [method]: obj }; - }); -} - -function main() { - combineSchemas(schemas); - apiRoutes(); - - fs.writeFileSync( - openapiPath, - JSON.stringify(specification, null, 4).replaceAll("#/definitions", "#/components/schemas").replaceAll("bigint", "number") - ); -} - -main(); diff --git a/api/scripts/generate_schema.js b/api/scripts/generate_schema.js new file mode 100644 index 00000000..22d0b02e --- /dev/null +++ b/api/scripts/generate_schema.js @@ -0,0 +1,70 @@ +// https://mermade.github.io/openapi-gui/# +// https://editor.swagger.io/ +import path from "path"; +import fs from "fs"; +import * as TJS from "typescript-json-schema"; +import "missing-native-js-functions"; +const schemaPath = path.join(__dirname, "..", "assets", "schemas.json"); + +const settings = { + required: true, + ignoreErrors: true, + excludePrivate: true, + defaultNumberType: "integer", + noExtraProps: true, + defaultProps: false +}; +const compilerOptions = { + strictNullChecks: true +}; +const Excluded = [ + "DefaultSchema", + "Schema", + "EntitySchema", + "ServerResponse", + "Http2ServerResponse", + "global.Express.Response", + "Response", + "e.Response", + "request.Response", + "supertest.Response" +]; + +function main() { + const program = TJS.getProgramFromFiles(walk(path.join(__dirname, "..", "src", "routes")), compilerOptions); + const generator = TJS.buildGenerator(program, settings); + if (!generator || !program) return; + + const schemas = generator.getUserSymbols().filter((x) => (x.endsWith("Schema") || x.endsWith("Response")) && !Excluded.includes(x)); + console.log(schemas); + + var definitions = {}; + + for (const name of schemas) { + const part = TJS.generateSchema(program, name, settings, [], generator); + if (!part) continue; + + definitions = { ...definitions, [name]: { ...part } }; + } + + fs.writeFileSync(schemaPath, JSON.stringify(definitions, null, 4)); +} + +main(); + +function walk(dir) { + var results = []; + var list = fs.readdirSync(dir); + list.forEach(function (file) { + file = dir + "/" + file; + var stat = fs.statSync(file); + if (stat && stat.isDirectory()) { + /* Recurse into a subdirectory */ + results = results.concat(walk(file)); + } else { + if (!file.endsWith(".ts")) return; + results.push(file); + } + }); + return results; +} -- cgit 1.5.1