diff --git a/gulpfile.ts b/gulpfile.ts
index 0bc18dd7c..6807b6d57 100644
--- a/gulpfile.ts
+++ b/gulpfile.ts
@@ -48,7 +48,7 @@ if (isDebug) {
const constants = require('./src/const.json');
-require('./src/web/docs/api/endpoints/gulpfile.ts');
+require('./src/web/docs/api/gulpfile.ts');
gulp.task('build', [
'build:js',
@@ -61,7 +61,7 @@ gulp.task('build', [
gulp.task('rebuild', ['clean', 'build']);
gulp.task('build:doc', [
- 'doc:endpoints',
+ 'doc:api',
'doc:styles'
]);
diff --git a/src/web/docs/api/endpoints/posts/create.yaml b/src/web/docs/api/endpoints/posts/create.yaml
index 498a99159..5e2307dab 100644
--- a/src/web/docs/api/endpoints/posts/create.yaml
+++ b/src/web/docs/api/endpoints/posts/create.yaml
@@ -10,7 +10,7 @@ params:
optional: true
desc:
ja: "投稿の本文"
- en: "Text of a post"
+ en: "The text of your post"
- name: "media_ids"
type: "id(DriveFile)[]"
optional: true
@@ -22,19 +22,19 @@ params:
optional: true
desc:
ja: "返信する投稿"
- en: "A post you want to reply"
+ en: "The post you want to reply"
- name: "repost_id"
type: "id(Post)"
optional: true
desc:
ja: "引用する投稿"
- en: "A post you want to quote"
+ en: "The post you want to quote"
- name: "poll"
type: "object"
optional: true
desc:
ja: "投票"
- en: "A poll"
+ en: "The poll"
defName: "poll"
def:
- name: "choices"
diff --git a/src/web/docs/api/endpoints/style.styl b/src/web/docs/api/endpoints/style.styl
index ab74e100b..07fb7ec2a 100644
--- a/src/web/docs/api/endpoints/style.styl
+++ b/src/web/docs/api/endpoints/style.styl
@@ -1,4 +1,4 @@
-@import "../../style"
+@import "../style"
#url
padding 8px 12px
@@ -6,13 +6,3 @@
color #fff
background #222e40
border-radius 4px
-
-table
- .name
- font-weight bold
-
- .name
- .type
- .optional
- font-family Consolas, 'Courier New', Courier, Monaco, monospace
-
diff --git a/src/web/docs/api/endpoints/view.pug b/src/web/docs/api/endpoints/view.pug
index 841ca8b3f..cebef9fa5 100644
--- a/src/web/docs/api/endpoints/view.pug
+++ b/src/web/docs/api/endpoints/view.pug
@@ -1,63 +1,30 @@
-doctype html
+extends ../../layout.pug
+include ../mixins
-mixin i18n(xs)
- each text, lang in xs
- span(class=`i18n ${lang}`)= text
+block title
+ | #{endpoint} | Misskey API
-mixin table(params)
- table
- thead: tr
- th Name
- th Type
- th Optional
- th Description
- tbody
- each param in params
- tr
- td.name= param.name
- td.type
- if param.kind == 'id'
- | #{param.type} (
- a(href=`/docs/api/entities/${param.entity}`)= param.entity
- | ID)
- else if param.kind == 'entity'
- | #{param.type} (
- a(href=`/docs/api/entities/${param.entity}`)= param.entity
- | )
- else if param.kind == 'object'
- | #{param.type} (
- a(href=`#${param.defName}`)= param.defName
- | )
- else
- = param.type
- td.optional= param.optional.toString()
- td.desc: +i18n(param.desc)
+block meta
+ link(rel="stylesheet" href="/assets/docs/api/endpoints/style.css")
-html
- head
- meta(charset="UTF-8")
- title #{endpoint} | Misskey API
- link(rel="stylesheet" href="/assets/docs/api/endpoints/style.css")
+block main
+ h1= endpoint
- body
- main
- h1= endpoint
+ p#url= url
- p#url= url
+ p#desc: +i18n(desc)
- p#desc: +i18n(desc)
+ section
+ h2 Params
+ +propTable(params)
- section
- h2 Params
- +table(params)
+ if paramDefs
+ each paramDef in paramDefs
+ section(id= paramDef.name)
+ h3= paramDef.name
+ +propTable(paramDef.params)
- if paramDefs
- each paramDef in paramDefs
- section(id= paramDef.name)
- h3= paramDef.name
- +table(paramDef.params)
-
- section
- h2 Response
- +table(res)
+ section
+ h2 Response
+ +propTable(res)
diff --git a/src/web/docs/api/entities/post.yaml b/src/web/docs/api/entities/post.yaml
new file mode 100644
index 000000000..551f3b7c3
--- /dev/null
+++ b/src/web/docs/api/entities/post.yaml
@@ -0,0 +1,124 @@
+name: "Post"
+
+desc:
+ ja: "投稿。"
+ en: "A post."
+
+props:
+ - name: "id"
+ type: "id"
+ optional: false
+ desc:
+ ja: "投稿ID"
+ en: "The ID of this post"
+ - name: "created_at"
+ type: "date"
+ optional: false
+ desc:
+ ja: "投稿日時"
+ en: "The posted date of this post"
+ - name: "text"
+ type: "string"
+ optional: true
+ desc:
+ ja: "投稿の本文"
+ en: "The text of this post"
+ - name: "media_ids"
+ type: "id(DriveFile)[]"
+ optional: true
+ desc:
+ ja: "添付されているメディアのID"
+ en: "The IDs of the attached media"
+ - name: "media"
+ type: "entity(DriveFile)[]"
+ optional: true
+ desc:
+ ja: "添付されているメディア"
+ en: "The attached media"
+ - name: "user_id"
+ type: "id(User)"
+ optional: false
+ desc:
+ ja: "投稿者ID"
+ en: "The ID of author of this post"
+ - name: "user"
+ type: "entity(User)"
+ optional: true
+ desc:
+ ja: "投稿者"
+ en: "The author of this post"
+ - name: "my_reaction"
+ type: "string"
+ optional: true
+ desc:
+ ja: "この投稿に対する自分のリアクション"
+ en: "The your reaction of this post"
+ - name: "reaction_counts"
+ type: "object"
+ optional: false
+ desc:
+ ja: "リアクションをキーとし、この投稿に対するそのリアクションの数を値としたオブジェクト"
+ - name: "reply_id"
+ type: "id(Post)"
+ optional: true
+ desc:
+ ja: "返信した投稿のID"
+ en: "The ID of the replyed post"
+ - name: "reply"
+ type: "entity(Post)"
+ optional: true
+ desc:
+ ja: "返信した投稿"
+ en: "The replyed post"
+ - name: "repost_id"
+ type: "id(Post)"
+ optional: true
+ desc:
+ ja: "引用した投稿のID"
+ en: "The ID of the quoted post"
+ - name: "repost"
+ type: "entity(Post)"
+ optional: true
+ desc:
+ ja: "引用した投稿"
+ en: "The quoted post"
+ - name: "poll"
+ type: "object"
+ optional: true
+ desc:
+ ja: "投票"
+ en: "The poll"
+ defName: "poll"
+ def:
+ - name: "choices"
+ type: "object[]"
+ optional: false
+ desc:
+ ja: "投票の選択肢"
+ en: "The choices of this poll"
+ defName: "choice"
+ def:
+ - name: "id"
+ type: "number"
+ optional: false
+ desc:
+ ja: "選択肢ID"
+ en: "The ID of this choice"
+ - name: "is_voted"
+ type: "boolean"
+ optional: true
+ desc:
+ ja: "自分がこの選択肢に投票したかどうか"
+ en: "Whether you voted to this choice"
+ - name: "text"
+ type: "string"
+ optional: false
+ desc:
+ ja: "選択肢本文"
+ en: "The text of this choice"
+ - name: "votes"
+ type: "number"
+ optional: false
+ desc:
+ ja: "この選択肢に投票された数"
+ en: "The number voted for this choice"
diff --git a/src/web/docs/api/entities/style.styl b/src/web/docs/api/entities/style.styl
new file mode 100644
index 000000000..bddf0f53a
--- /dev/null
+++ b/src/web/docs/api/entities/style.styl
@@ -0,0 +1 @@
+@import "../style"
diff --git a/src/web/docs/api/entities/view.pug b/src/web/docs/api/entities/view.pug
new file mode 100644
index 000000000..f210582f1
--- /dev/null
+++ b/src/web/docs/api/entities/view.pug
@@ -0,0 +1,23 @@
+extends ../../layout.pug
+include ../mixins
+
+block title
+ | #{name} | Misskey API
+
+block meta
+ link(rel="stylesheet" href="/assets/docs/api/entities/style.css")
+
+block main
+ h1= name
+
+ p#desc: +i18n(desc)
+
+ section
+ h2 Properties
+ +propTable(props)
+
+ if propDefs
+ each propDef in propDefs
+ section(id= propDef.name)
+ h3= propDef.name
+ +propTable(propDef.params)
diff --git a/src/web/docs/api/endpoints/gulpfile.ts b/src/web/docs/api/gulpfile.ts
similarity index 50%
rename from src/web/docs/api/endpoints/gulpfile.ts
rename to src/web/docs/api/gulpfile.ts
index e375447c5..05567b623 100644
--- a/src/web/docs/api/endpoints/gulpfile.ts
+++ b/src/web/docs/api/gulpfile.ts
@@ -10,12 +10,15 @@ import * as pug from 'pug';
import * as yaml from 'js-yaml';
import * as mkdirp from 'mkdirp';
-import config from './../../../../conf';
+import config from './../../../conf';
+
+const kebab = string => string.replace(/([a-z])([A-Z])/g, '$1-$2').replace(/\s+/g, '-').toLowerCase();
const parseParam = param => {
- const id = param.type.match(/^id\((.+?)\)/);
+ const id = param.type.match(/^id\((.+?)\)|^id/);
const entity = param.type.match(/^entity\((.+?)\)/);
const isObject = /^object/.test(param.type);
+ const isDate = /^date/.test(param.type);
const isArray = /\[\]$/.test(param.type);
if (id) {
param.kind = 'id';
@@ -36,30 +39,53 @@ const parseParam = param => {
if (isObject) {
param.kind = 'object';
}
+ if (isDate) {
+ param.kind = 'date';
+ param.type = 'string';
+ if (isArray) {
+ param.type += '[]';
+ }
+ }
return param;
};
+const sortParams = params => {
+ params.sort((a, b) => {
+ if (a.name < b.name)
+ return -1;
+ if (a.name > b.name)
+ return 1;
+ return 0;
+ });
+ return params;
+};
+
const extractDefs = params => {
- const defs = [];
+ let defs = [];
params.forEach(param => {
if (param.def) {
defs.push({
name: param.defName,
- params: param.def.map(p => parseParam(p))
+ params: sortParams(param.def.map(p => parseParam(p)))
});
const childDefs = extractDefs(param.def);
- defs.concat(childDefs);
+ defs = defs.concat(childDefs);
}
});
return defs;
};
-gulp.task('doc:endpoints', () => {
+gulp.task('doc:api', [
+ 'doc:api:endpoints',
+ 'doc:api:entities'
+]);
+
+gulp.task('doc:api:endpoints', () => {
glob('./src/web/docs/api/endpoints/**/*.yaml', (globErr, files) => {
if (globErr) {
console.error(globErr);
@@ -72,10 +98,11 @@ gulp.task('doc:endpoints', () => {
endpoint: ep.endpoint,
url: `${config.api_url}/${ep.endpoint}`,
desc: ep.desc,
- params: ep.params.map(p => parseParam(p)),
+ params: sortParams(ep.params.map(p => parseParam(p))),
paramDefs: extractDefs(ep.params),
- res: ep.res.map(p => parseParam(p)),
- resDefs: extractDefs(ep.res)
+ res: sortParams(ep.res.map(p => parseParam(p))),
+ resDefs: extractDefs(ep.res),
+ kebab
};
pug.renderFile('./src/web/docs/api/endpoints/view.pug', vars, (renderErr, html) => {
if (renderErr) {
@@ -94,3 +121,36 @@ gulp.task('doc:endpoints', () => {
});
});
});
+
+gulp.task('doc:api:entities', () => {
+ glob('./src/web/docs/api/entities/**/*.yaml', (globErr, files) => {
+ if (globErr) {
+ console.error(globErr);
+ return;
+ }
+ files.forEach(file => {
+ const entity = yaml.safeLoad(fs.readFileSync(file, 'utf-8'));
+ const vars = {
+ name: entity.name,
+ desc: entity.desc,
+ props: sortParams(entity.props.map(p => parseParam(p))),
+ propDefs: extractDefs(entity.props),
+ kebab
+ };
+ pug.renderFile('./src/web/docs/api/entities/view.pug', vars, (renderErr, html) => {
+ if (renderErr) {
+ console.error(renderErr);
+ return;
+ }
+ const htmlPath = `./built/web/docs/api/entities/${kebab(entity.name)}.html`;
+ mkdirp(path.dirname(htmlPath), (mkdirErr) => {
+ if (mkdirErr) {
+ console.error(mkdirErr);
+ return;
+ }
+ fs.writeFileSync(htmlPath, html, 'utf-8');
+ });
+ });
+ });
+ });
+});
diff --git a/src/web/docs/api/mixins.pug b/src/web/docs/api/mixins.pug
new file mode 100644
index 000000000..b302c7826
--- /dev/null
+++ b/src/web/docs/api/mixins.pug
@@ -0,0 +1,33 @@
+mixin propTable(props)
+ table.props
+ thead: tr
+ th Name
+ th Type
+ th Optional
+ th Description
+ tbody
+ each prop in props
+ tr
+ td.name= prop.name
+ td.type
+ i= prop.type
+ if prop.kind == 'id'
+ if prop.entity
+ | (
+ a(href=`/docs/api/entities/${kebab(prop.entity)}`)= prop.entity
+ | ID)
+ else
+ | (ID)
+ else if prop.kind == 'entity'
+ | (
+ a(href=`/docs/api/entities/${kebab(prop.entity)}`)= prop.entity
+ | )
+ else if prop.kind == 'object'
+ if prop.def
+ | (
+ a(href=`#${prop.defName}`)= prop.defName
+ | )
+ else if prop.kind == 'date'
+ | (Date)
+ td.optional= prop.optional.toString()
+ td.desc: +i18n(prop.desc)
diff --git a/src/web/docs/api/style.styl b/src/web/docs/api/style.styl
new file mode 100644
index 000000000..3675a4da6
--- /dev/null
+++ b/src/web/docs/api/style.styl
@@ -0,0 +1,11 @@
+@import "../style"
+
+table.props
+ .name
+ font-weight bold
+
+ .name
+ .type
+ .optional
+ font-family Consolas, 'Courier New', Courier, Monaco, monospace
+
diff --git a/src/web/docs/layout.pug b/src/web/docs/layout.pug
new file mode 100644
index 000000000..68ca9eb62
--- /dev/null
+++ b/src/web/docs/layout.pug
@@ -0,0 +1,16 @@
+doctype html
+
+mixin i18n(xs)
+ each text, lang in xs
+ span(class=`i18n ${lang}`)!= text
+
+html
+ head
+ meta(charset="UTF-8")
+ title
+ block title
+ block meta
+
+ body
+ main
+ block main