Markdown--APIドキュメントを書く
2495 ワード
最近towerでmarkdownでプロジェクトのAPIドキュメントを書いたので、使いやすい感じです.主にアンカーポイントを利用してインタフェースの詳細にジャンプします.Powerはhtmlを生産する際にタイトルラベルにidを入れます.
変換
ユーザー情報インタフェースのリスト
リードインタフェース
users/mobile
ユーザーの携帯番号を取得
書き込みインタフェース
users/mobile/put
ユーザーの携帯番号をアップロード
ユーザ情報インタフェースの詳細 users/mobile
ユーザーの携帯番号を取得
権限検証が必要かどうか
はい
要求パラメータ
||必須|タイプ|説明|:-----------------:|::----------------------------||userId|true|int|ユーザーID|
リクエストメソッド
GET
呼び出しサンプル
結果を返す
***JSON例***
***エラー戻り値***
|code|msg|説明|:-----------------:|:---------------------||1010|xxxx|xxxxxx|
その他のエラー戻り値とエラーコードについては、エラーコードの説明を参照してください.
ErrorCode
エラーコード照合テーブル
システムレベルエラー
|エラーコード|戻りmsg|詳細説明|:-----------------:|:|:|:|400|システムエラー、再試行をお待ちください|要求パラメータにエラーがあります|401|システムエラー、再試行をお待ちください|ユーザーが登録していません|404|システムエラー、再試行をお待ちください|リソースが見つかりません|405|システムエラー、再試行をお待ちください|要求方法がサポートしていません|500|システムエラー、再試行をお待ちください|サーバエラー|
ビジネス・レベルのエラー
エラーコード
詳細な説明
1010
xxxx
MARKDOWN:
* #### users/mobile
* ## ErrorCode
変換
users/mobile
ErrorCode
ユーザー情報インタフェースのリスト
リードインタフェース
users/mobile
ユーザーの携帯番号を取得
書き込みインタフェース
users/mobile/put
ユーザーの携帯番号をアップロード
ユーザ情報インタフェースの詳細
ユーザーの携帯番号を取得
権限検証が必要かどうか
はい
要求パラメータ
||必須|タイプ|説明|:-----------------:|::----------------------------||userId|true|int|ユーザーID|
リクエストメソッド
GET
呼び出しサンプル
users/mobile?userId=214
結果を返す
***JSON例***
{
"code": 0,
"msg": "",
"data": {
"mobile": 150888888888
}
}
***エラー戻り値***
|code|msg|説明|:-----------------:|:---------------------||1010|xxxx|xxxxxx|
その他のエラー戻り値とエラーコードについては、エラーコードの説明を参照してください.
ErrorCode
エラーコード照合テーブル
システムレベルエラー
|エラーコード|戻りmsg|詳細説明|:-----------------:|:|:|:|400|システムエラー、再試行をお待ちください|要求パラメータにエラーがあります|401|システムエラー、再試行をお待ちください|ユーザーが登録していません|404|システムエラー、再試行をお待ちください|リソースが見つかりません|405|システムエラー、再試行をお待ちください|要求方法がサポートしていません|500|システムエラー、再試行をお待ちください|サーバエラー|
ビジネス・レベルのエラー
エラーコード
詳細な説明
1010
xxxx
MARKDOWN:
##
---
####
| | |
|:-------------:|:-------------|
| [users/mobile](#users-mobile) | |
####
| | |
|:-------------:|:-------------|
| [users/mobile/put](#users-mobile-put) | |
##
* #### users/mobile
---
#####
---
#####
---
| | | | |
|:-------------:|:-------------|:-------------|
| userId | true | int | ID |
#####
---
GET
#####
---
` ``
users/mobile?userId=214
` ``
#####
---
*** JSON ***
` ``
{
"code": 0,
"msg": "",
"data": {
"mobile": 150888888888
}
}
` ``
*** ***
| code | msg | |
|:-------------:|:-------------|
| 1010 | xxxx | xxxx |
， [ ](#errorcode)
## ErrorCode
###
---
#####
---
| | msg | |
|:-------------:|:-------------|
| 400 | ， | |
| 401 | ， | |
| 404 | ， | |
| 405 | ， | |
| 500 | ， | |
#####
---
| | |
|:-------------:|:-------------|
| 1010 | xxxx |