Improve doc

This commit is contained in:
syuilo 2019-02-25 04:18:09 +09:00
parent 47d4dcfdf5
commit 60c9a6528f
No known key found for this signature in database
GPG key ID: BDC4C49D06AB9D69
14 changed files with 52 additions and 12 deletions

View file

@ -7,6 +7,7 @@ export type Param = {
validator: Context<any>;
transform?: any;
default?: any;
deprecated?: boolean;
desc?: { [key: string]: string };
ref?: string;
};

View file

@ -21,6 +21,20 @@ export const meta = {
}
},
res: {
type: 'object',
properties: {
token: {
type: 'string',
description: 'セッションのトークン'
},
url: {
type: 'string',
description: 'セッションのURL'
},
}
},
errors: {
noSuchApp: {
message: 'No such app.',

View file

@ -29,6 +29,21 @@ export const meta = {
}
},
res: {
type: 'object',
properties: {
accessToken: {
type: 'string',
description: 'ユーザーのアクセストークン',
},
user: {
type: 'User',
description: '認証したユーザー'
},
}
},
errors: {
noSuchApp: {
message: 'No such app.',

View file

@ -41,6 +41,7 @@ export const meta = {
media: {
validator: $.optional.bool,
deprecated: true,
desc: {
'ja-JP': 'ファイルが添付された投稿に限定するか否か (このパラメータは廃止予定です。代わりに withFiles を使ってください。)'
}

View file

@ -138,6 +138,7 @@ export const meta = {
mediaIds: {
validator: $.optional.arr($.type(ID)).unique().range(1, 4),
transform: transformMany,
deprecated: true,
desc: {
'ja-JP': '添付するファイル (このパラメータは廃止予定です。代わりに fileIds を使ってください。)'
}

View file

@ -24,6 +24,7 @@ export const meta = {
mediaOnly: {
validator: $.optional.bool,
deprecated: true,
desc: {
'ja-JP': 'ファイルが添付された投稿に限定するか否か (このパラメータは廃止予定です。代わりに withFiles を使ってください。)'
}

View file

@ -88,6 +88,7 @@ export const meta = {
mediaOnly: {
validator: $.optional.bool,
deprecated: true,
desc: {
'ja-JP': 'true にすると、ファイルが添付された投稿だけ取得します (このパラメータは廃止予定です。代わりに withFiles を使ってください。)'
}

View file

@ -25,6 +25,7 @@ export const meta = {
mediaOnly: {
validator: $.optional.bool,
deprecated: true,
desc: {
'ja-JP': 'ファイルが添付された投稿に限定するか否か (このパラメータは廃止予定です。代わりに withFiles を使ってください。)'
}

View file

@ -64,6 +64,7 @@ export const meta = {
media: {
validator: $.optional.nullable.bool,
default: null as any,
deprecated: true,
desc: {
'ja-JP': 'ファイルが添付された投稿に限定するか否か (このパラメータは廃止予定です。代わりに withFiles を使ってください。)'
}

View file

@ -89,6 +89,7 @@ export const meta = {
mediaOnly: {
validator: $.optional.bool,
deprecated: true,
desc: {
'ja-JP': 'true にすると、ファイルが添付された投稿だけ取得します (このパラメータは廃止予定です。代わりに withFiles を使ってください。)'
}

View file

@ -98,6 +98,7 @@ export const meta = {
mediaOnly: {
validator: $.optional.bool,
deprecated: true,
desc: {
'ja-JP': 'true にすると、ファイルが添付された投稿だけ取得します (このパラメータは廃止予定です。代わりに withFiles を使ってください。)'
}

View file

@ -105,6 +105,7 @@ export const meta = {
mediaOnly: {
validator: $.optional.bool,
default: false,
deprecated: true,
desc: {
'ja-JP': 'true にすると、ファイルが添付された投稿だけ取得します (このパラメータは廃止予定です。代わりに withFiles を使ってください。)'
}

View file

@ -3,16 +3,16 @@ import config from '../../../config';
export const description = `
## Usage
**APIはすべてPOSTでリクエスト/JSON形式です**
APIは認証情報()\`i\`というパラメータでアクセストークンを添付してください。
APIはリクエストに認証情報(APIキー)\`i\`というパラメータでAPIキーを添付してください。
###
> API
### APIキーを取得す
> APIAPIキーを取得できま
> ()
###
APIを利用する際にはMisskeyに発行してもらいます
### APIキーを取得す
APIキーをアプリケーションが扱うのはセキュリティ上のリスクがあるの
APIを利用する際にはAPIキーを発行します
#### 1.
Webサービス()Misskeyに登録します
@ -25,8 +25,7 @@ export const description = `
#### 2.
使
[${config.apiUrl}/auth/session/generate](#operation/auth/session/generate) appSecret
JSONでPOSTです
[${config.apiUrl}/auth/session/generate](#operation/auth/session/generate) \`appSecret\`としてシークレットキーを含めたリクエストを送信します。
URLが取得できるのでURLをブラウザで表示し
URLを設定している場合
@ -34,14 +33,14 @@ export const description = `
URLを設定していない場合(())
#### 3.
#### 3.
[${config.apiUrl}/auth/session/userkey](#operation/auth/session/userkey)
*+sha256したもの*APIにリクエストできます
*+sha256したもの*APIキーとしAPIにリクエストできます
:
APIキーの生成方法を擬似コードで表すと次のようになりま:
\`\`\` js
const i = sha256(userToken + secretKey);
\`\`\`

View file

@ -56,6 +56,7 @@ export function genOpenapiSpec(lang = 'ja-JP') {
return {
description: (param.data || {}).desc,
default: (param.data || {}).default,
deprecated: (param.data || {}).deprecated,
...((param.data || {}).default ? { default: (param.data || {}).default } : {}),
type: param.name === 'ID' ? 'string' : param.name.toLowerCase(),
...(param.name === 'ID' ? { example: 'xxxxxxxxxxxxxxxxxxxxxxxx', format: 'id' } : {}),
@ -97,6 +98,7 @@ export function genOpenapiSpec(lang = 'ja-JP') {
for (const [k, v] of Object.entries(endpoint.meta.params)) {
if (v.validator.data == null) v.validator.data = {};
if (v.desc) v.validator.data.desc = v.desc[lang];
if (v.deprecated) v.validator.data.deprecated = v.deprecated;
if (v.default) v.validator.data.default = v.default;
porops[k] = v.validator;
}