sim1222/test1
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Improve doc

Browse Source
This commit is contained in:
syuilo
2019-02-25 04:18:09 +09:00
parent 47d4dcfdf5
commit 60c9a6528f
14 changed files with 52 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
src/server/api/endpoints.ts
View File

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

14
src/server/api/endpoints/auth/session/generate.ts
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.',

15
src/server/api/endpoints/auth/session/userkey.ts
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.',

1
src/server/api/endpoints/notes.ts
View File

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

1
src/server/api/endpoints/notes/create.ts
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 を使ってください。)'
}

1
src/server/api/endpoints/notes/global-timeline.ts
View File

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

1
src/server/api/endpoints/notes/hybrid-timeline.ts
View File

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

1
src/server/api/endpoints/notes/local-timeline.ts
View File

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

1
src/server/api/endpoints/notes/search-by-tag.ts
View File

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

1
src/server/api/endpoints/notes/timeline.ts
View File

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

1
src/server/api/endpoints/notes/user-list-timeline.ts
View File

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

1
src/server/api/endpoints/users/notes.ts
View File

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

23
src/server/api/openapi/description.ts
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キーを取得する
「設定 > API」で、自分のAPIキーを取得できます。
> アカウントを不正利用される可能性があるため、このトークンは第三者に教えないでください(アプリなどにも入力しないでください)。
### アプリケーションとしてアクセストークンを取得する
直接ユーザーのアクセストークンをアプリケーションが扱うのはセキュリティ上のリスクがあるので、
アプリケーションから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);
\`\`\`

2
src/server/api/openapi/gen-spec.ts
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;
}