Sharkey/src/server/web/docs.ts

260 lines
6.5 KiB
TypeScript
Raw Normal View History

2017-12-16 18:41:22 +02:00
/**
2018-04-13 00:06:18 +03:00
* Docs
2017-12-16 18:41:22 +02:00
*/
2018-07-06 14:27:48 +03:00
import * as fs from 'fs';
import * as path from 'path';
import * as showdown from 'showdown';
2018-07-16 19:11:36 +03:00
import 'showdown-highlightjs-extension';
2018-04-13 06:05:24 +03:00
import ms = require('ms');
2018-04-13 00:06:18 +03:00
import * as Router from 'koa-router';
import * as send from 'koa-send';
2018-07-07 21:21:16 +03:00
import { Context, ObjectContext } from 'cafy';
2018-07-06 14:27:48 +03:00
import * as glob from 'glob';
import * as yaml from 'js-yaml';
2018-07-05 20:58:29 +03:00
import config from '../../config';
2018-07-07 21:13:20 +03:00
import { licenseHtml } from '../../misc/license';
2018-07-06 14:27:48 +03:00
const constants = require('../../const.json');
2018-07-18 00:53:31 +03:00
import endpoints from '../api/endpoints';
2018-11-09 15:02:48 +02:00
const locales = require('../../../locales');
import * as nestedProperty from 'nested-property';
2017-12-16 18:41:22 +02:00
2019-02-02 09:16:31 +02:00
function getLang(lang: string): string {
if (['en-US', 'ja-JP'].includes(lang)) {
return lang;
} else {
return 'en-US';
}
}
2018-07-06 14:27:48 +03:00
async function genVars(lang: string): Promise<{ [key: string]: any }> {
const vars = {} as { [key: string]: any };
vars['lang'] = lang;
2018-07-15 13:35:20 +03:00
const cwd = path.resolve(__dirname + '/../../../') + '/';
2018-07-15 13:29:15 +03:00
2018-07-15 21:53:03 +03:00
vars['endpoints'] = endpoints;
2018-07-06 14:27:48 +03:00
2018-07-15 13:29:15 +03:00
const entities = glob.sync('src/docs/api/entities/**/*.yaml', { cwd });
2018-07-06 14:27:48 +03:00
vars['entities'] = entities.map(x => {
2018-12-02 12:05:08 +02:00
const _x = yaml.safeLoad(fs.readFileSync(cwd + x, 'utf-8'));
2018-07-06 14:27:48 +03:00
return _x.name;
});
2018-07-15 16:00:05 +03:00
const docs = glob.sync(`src/docs/**/*.${lang}.md`, { cwd });
2018-07-06 14:27:48 +03:00
vars['docs'] = {};
for (const x of docs) {
2018-07-15 16:00:05 +03:00
const [, name] = x.match(/docs\/(.+?)\.(.+?)\.md$/);
2018-07-06 14:27:48 +03:00
if (vars['docs'][name] == null) {
vars['docs'][name] = {
name,
title: {}
};
}
2018-07-15 13:35:20 +03:00
vars['docs'][name]['title'][lang] = fs.readFileSync(cwd + x, 'utf-8').match(/^# (.+?)\r?\n/)[1];
}
2018-07-06 14:27:48 +03:00
vars['kebab'] = (string: string) => string.replace(/([a-z])([A-Z])/g, '$1-$2').replace(/\s+/g, '-').toLowerCase();
vars['config'] = config;
vars['copyright'] = constants.copyright;
vars['license'] = licenseHtml;
2018-11-09 15:02:48 +02:00
vars['i18n'] = (key: string) => nestedProperty.get(locales[lang], key);
2018-07-06 14:27:48 +03:00
return vars;
}
2018-07-05 20:58:29 +03:00
// WIP type
2018-11-01 20:41:09 +02:00
const parseParamDefinition = (key: string, x: any) => {
2018-07-05 20:58:29 +03:00
return Object.assign({
name: key,
2018-11-01 20:41:09 +02:00
type: x.validator.getType()
}, x);
2018-07-05 20:58:29 +03:00
};
2018-07-07 07:34:42 +03:00
const parsePropDefinition = (key: string, prop: any) => {
const id = prop.type.match(/^id\((.+?)\)|^id/);
const entity = prop.type.match(/^entity\((.+?)\)/);
const isObject = /^object/.test(prop.type);
const isDate = /^date/.test(prop.type);
const isArray = /\[\]$/.test(prop.type);
2018-07-06 14:27:48 +03:00
if (id) {
2018-07-07 07:34:42 +03:00
prop.kind = 'id';
prop.type = 'string';
prop.entity = id[1];
2018-07-06 14:27:48 +03:00
if (isArray) {
2018-07-07 07:34:42 +03:00
prop.type += '[]';
2018-07-06 14:27:48 +03:00
}
}
if (entity) {
2018-07-07 07:34:42 +03:00
prop.kind = 'entity';
prop.type = 'object';
prop.entity = entity[1];
2018-07-06 14:27:48 +03:00
if (isArray) {
2018-07-07 07:34:42 +03:00
prop.type += '[]';
2018-07-06 14:27:48 +03:00
}
}
if (isObject) {
2018-07-07 07:34:42 +03:00
prop.kind = 'object';
if (prop.props) {
prop.hasDef = true;
}
2018-07-06 14:27:48 +03:00
}
if (isDate) {
2018-07-07 07:34:42 +03:00
prop.kind = 'date';
prop.type = 'string';
2018-07-06 14:27:48 +03:00
if (isArray) {
2018-07-07 07:34:42 +03:00
prop.type += '[]';
2018-07-06 14:27:48 +03:00
}
}
2018-07-07 07:34:42 +03:00
if (prop.optional) {
prop.type += '?';
2018-07-06 14:27:48 +03:00
}
2018-07-07 07:34:42 +03:00
prop.name = key;
return prop;
2018-07-06 14:27:48 +03:00
};
2018-07-18 13:24:31 +03:00
const sortParams = (params: Array<{ name: string }>) => {
2018-07-05 20:58:29 +03:00
return params;
};
// WIP type
2018-07-07 07:34:42 +03:00
const extractParamDefRef = (params: Context[]) => {
2018-07-05 20:58:29 +03:00
let defs: any[] = [];
for (const param of params) {
2018-07-05 20:58:29 +03:00
if (param.data && param.data.ref) {
const props = (param as ObjectContext<any>).props;
defs.push({
name: param.data.ref,
2018-07-07 07:34:42 +03:00
params: sortParams(Object.keys(props).map(k => parseParamDefinition(k, props[k])))
2018-07-05 20:58:29 +03:00
});
2018-07-07 07:34:42 +03:00
const childDefs = extractParamDefRef(Object.keys(props).map(k => props[k]));
2018-07-06 14:27:48 +03:00
defs = defs.concat(childDefs);
}
}
2018-07-06 14:27:48 +03:00
return sortParams(defs);
};
2018-07-07 07:34:42 +03:00
const extractPropDefRef = (props: any[]) => {
2018-07-06 14:27:48 +03:00
let defs: any[] = [];
for (const [k, v] of Object.entries(props)) {
2018-07-07 07:34:42 +03:00
if (v.props) {
2018-07-06 14:27:48 +03:00
defs.push({
2018-07-07 07:34:42 +03:00
name: k,
props: sortParams(Object.entries(v.props).map(([k, v]) => parsePropDefinition(k, v)))
2018-07-06 14:27:48 +03:00
});
2018-07-07 07:34:42 +03:00
const childDefs = extractPropDefRef(v.props);
2018-07-05 20:58:29 +03:00
defs = defs.concat(childDefs);
}
}
2018-07-05 20:58:29 +03:00
return sortParams(defs);
};
2018-04-13 00:06:18 +03:00
const router = new Router();
2017-12-16 18:41:22 +02:00
2018-04-13 06:05:24 +03:00
router.get('/assets/*', async ctx => {
2019-01-22 14:42:05 +02:00
await send(ctx as any, ctx.params[0], {
root: `${__dirname}/../../docs/assets/`,
2018-09-19 08:22:46 +03:00
maxage: ms('1 days')
2018-04-13 06:05:24 +03:00
});
2018-04-13 00:06:18 +03:00
});
2017-12-16 18:41:22 +02:00
2018-07-05 20:58:29 +03:00
router.get('/*/api/endpoints/*', async ctx => {
2019-02-02 09:16:31 +02:00
const lang = getLang(ctx.params[0]);
2018-07-15 21:43:36 +03:00
const name = ctx.params[1];
2018-07-15 21:53:03 +03:00
const ep = endpoints.find(e => e.name === name);
2018-07-05 20:58:29 +03:00
const vars = {
2018-07-30 10:24:46 +03:00
id: `api/endpoints/${name}`,
2018-07-15 21:43:36 +03:00
title: name,
2018-07-16 00:19:19 +03:00
endpoint: ep.meta,
2018-07-30 10:24:46 +03:00
endpointUrl: {
2018-07-05 20:58:29 +03:00
host: config.api_url,
2018-07-15 21:43:36 +03:00
path: name
2018-07-05 20:58:29 +03:00
},
// @ts-ignore
2018-07-15 21:53:03 +03:00
params: ep.meta.params ? sortParams(Object.entries(ep.meta.params).map(([k, v]) => parseParamDefinition(k, v))) : null,
2018-11-01 20:32:24 +02:00
paramDefs: ep.meta.params ? extractParamDefRef(Object.values(ep.meta.params).map(x => x.validator)) : null,
2018-07-16 21:57:34 +03:00
res: ep.meta.res,
resProps: ep.meta.res && ep.meta.res.props ? sortParams(Object.entries(ep.meta.res.props).map(([k, v]) => parsePropDefinition(k, v))) : null,
2018-07-23 07:56:25 +03:00
resDefs: null as any, //extractPropDefRef(Object.entries(ep.res.props).map(([k, v]) => parsePropDefinition(k, v)))
2018-07-16 21:57:34 +03:00
src: `https://github.com/syuilo/misskey/tree/master/src/server/api/endpoints/${name}.ts`
2018-07-05 20:58:29 +03:00
};
await ctx.render('../../../../src/docs/api/endpoints/view', Object.assign(await genVars(lang), vars));
2018-11-19 22:29:51 +02:00
ctx.set('Cache-Control', 'public, max-age=300');
2018-07-06 14:27:48 +03:00
});
2018-07-05 20:58:29 +03:00
2018-07-06 14:27:48 +03:00
router.get('/*/api/entities/*', async ctx => {
2019-02-02 09:16:31 +02:00
const lang = getLang(ctx.params[0]);
2018-07-06 14:27:48 +03:00
const entity = ctx.params[1];
2018-07-06 06:17:38 +03:00
2018-12-02 12:05:08 +02:00
const x = yaml.safeLoad(fs.readFileSync(path.resolve(`${__dirname}/../../../src/docs/api/entities/${entity}.yaml`), 'utf-8'));
2018-07-05 20:58:29 +03:00
await ctx.render('../../../../src/docs/api/entities/view', Object.assign(await genVars(lang), {
2018-07-30 10:24:46 +03:00
id: `api/entities/${entity}`,
2018-07-06 14:27:48 +03:00
name: x.name,
desc: x.desc,
2018-07-07 07:34:42 +03:00
props: sortParams(Object.entries(x.props).map(([k, v]) => parsePropDefinition(k, v))),
propDefs: extractPropDefRef(x.props)
2018-07-06 14:27:48 +03:00
}));
2018-11-19 22:29:51 +02:00
ctx.set('Cache-Control', 'public, max-age=300');
2018-04-13 00:06:18 +03:00
});
2017-12-16 18:41:22 +02:00
2018-07-06 17:52:47 +03:00
router.get('/*/*', async ctx => {
2019-02-02 09:16:31 +02:00
const lang = getLang(ctx.params[0]);
2018-07-06 17:52:47 +03:00
const doc = ctx.params[1];
2018-07-15 13:05:19 +03:00
showdown.extension('urlExtension', () => ({
type: 'output',
regex: /%URL%/g,
replace: config.url
}));
2018-10-29 12:11:01 +02:00
showdown.extension('wsUrlExtension', () => ({
type: 'output',
regex: /%WS_URL%/g,
replace: config.ws_url
}));
2018-07-15 13:05:19 +03:00
showdown.extension('apiUrlExtension', () => ({
type: 'output',
regex: /%API_URL%/g,
replace: config.api_url
}));
const conv = new showdown.Converter({
tables: true,
2018-07-16 19:11:36 +03:00
extensions: ['urlExtension', 'apiUrlExtension', 'highlightjs']
2018-07-15 13:05:19 +03:00
});
const md = fs.readFileSync(`${__dirname}/../../../src/docs/${doc}.${lang}.md`, 'utf8');
await ctx.render('../../../../src/docs/article', Object.assign({
2018-07-30 10:24:46 +03:00
id: doc,
2018-07-15 15:48:57 +03:00
html: conv.makeHtml(md),
2018-07-16 21:57:34 +03:00
title: md.match(/^# (.+?)\r?\n/)[1],
src: `https://github.com/syuilo/misskey/tree/master/src/docs/${doc}.${lang}.md`
}, await genVars(lang)));
2018-11-19 22:29:51 +02:00
ctx.set('Cache-Control', 'public, max-age=300');
2018-07-06 17:52:47 +03:00
});
2018-04-13 06:05:24 +03:00
export default router;