47 lines
1.7 KiB
TypeScript
47 lines
1.7 KiB
TypeScript
import swagger from 'swagger-ui-express';
|
|
import jsonRefParser, {JSONSchema} from '@apidevtools/json-schema-ref-parser';
|
|
import oasParser from '@apidevtools/swagger-parser';
|
|
|
|
|
|
// modifies the normal swagger-ui-express package
|
|
// usage: app.use('/api-doc', api.serve(), api.setup());
|
|
// the paths property can be split using allOf
|
|
// further route documentation can be included in the x-doc property
|
|
|
|
export default class api {
|
|
static serve () {
|
|
return swagger.serve;
|
|
}
|
|
|
|
static setup () {
|
|
let apiDoc: JSONSchema = {};
|
|
jsonRefParser.bundle('api/api.yaml', (err, doc) => { // parse yaml
|
|
if(err) throw err;
|
|
apiDoc = doc;
|
|
apiDoc.paths = apiDoc.paths.allOf.reduce((s, e) => Object.assign(s, e)); // bundle routes
|
|
apiDoc = this.resolveXDoc(apiDoc);
|
|
oasParser.validate(apiDoc, (err, api) => { // validate oas schema
|
|
if (err) {
|
|
console.error(err);
|
|
}
|
|
else {
|
|
console.info(process.env.NODE_ENV === 'test' ? '' : 'API ok, version ' + api.info.version);
|
|
swagger.setup(apiDoc);
|
|
}
|
|
});
|
|
});
|
|
return swagger.setup(apiDoc, {customCssUrl: '/static/styles/swagger.css'})
|
|
}
|
|
|
|
private static resolveXDoc (doc) { // resolve x-doc properties recursively
|
|
Object.keys(doc).forEach(key => {
|
|
if (doc[key] !== null && doc[key].hasOwnProperty('x-doc')) { // add x-doc to description, is styled via css
|
|
doc[key].description += '<details class="docs"><summary>docs</summary>' + doc[key]['x-doc'] + '</details>';
|
|
}
|
|
else if (typeof doc[key] === 'object' && doc[key] !== null) { // go deeper into recursion
|
|
doc[key] = this.resolveXDoc(doc[key]);
|
|
}
|
|
});
|
|
return doc;
|
|
}
|
|
} |