闊歩文書管理

公式サイト：https://swagger.io/

高速あなたの書き込み  RESTFUL API のアノテーションによって、定義されたインタフェースとモデルをインタフェース文書化ツール、およびコードファイルは、ファイルストレージ一緒に配置または別々にすることができます。

優位

  • 文書の一貫性を維持するために??コードの定義ドキュメントアノテーション、コードによって簡単に
  • モデルの再利用は、冗長なドキュメント、より信頼性の高い文書を減らします
  • インターフェース呼び出しをテストするために、サードパーティ製のツールなしで、クライアントアクセスインタフェースは、あなたが直接インターフェイスをデバッグすることができます
  • サポート認証局、およびその他の機能

Laravel闊歩拡張

拡張送信元アドレス：https://github.com/DarkaOnLine/L5-Swagger

1 
2
 
作曲darkaonline / L5-闊歩必要と
PHPの職人のベンダーに：--provider "L5Swagger \ L5SwaggerServiceProvider"を公開

これは、コンフィギュレーション・ファイルが生成されます  l5-swagger.php設定項目に留意しなければなりません、

  • routes.api デフォルト値  api/documentation 闊歩ドキュメントルーティングシステムへのアクセス
  • routes.docs JSON文書格納パスファイルを解析闊歩コメントを生成しました
  • paths.annotations 効果的な注釈のパス設定、デフォルトの  base_path('app') アプリケーションパス
  • generate_always テスト環境は、この設定を有効にする必要があり、各訪問は、自動的に最新のドキュメント生成されたコメントを解析します
  • swagger_version デフォルト値は2.0で、提案3.0に修正します

以下のすべての注釈内容は、必要がに存在する  paths.annotations パス。

インタフェースのバージョン

@OA\Info すでにインターフェイスのバージョン、タイトル、説明、著者情報を定義しました。

1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11
 
/ ** 
* @OA \情報（
*バージョン= "1.0"、
*タイトル= "ユーザー管理"、
*説明= "ユーザーインタフェースモジュール"、
* @OA \ビジネスカード（
*名= "PHP開発支援"、
*メールアドレス= "dreamhelingfeng @ gmail.com" 
*）
*）
* /

やり方を要求するパス要求インタフェース

@OA\Get、@OA\Post インタフェースモード要求を定義します

例：USER_ID情報の前に要求するユーザ  /api/users/{user_id}
インタフェースのグループ化の設定は：tags界面に分類されます

1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21
 
/ ** 
 * 取得（\ @OA 
*パス= "/ API /ユーザ/ user_idを{}"、
*概要= "ユーザID情報に基づいて取得した"、
* = {タグ"ユーザー管理"}、
* @OAパラメータ\（
名前= * "のuser_id"、
* = "パス"に、
* = trueに必要な、
*説明= "ユーザーID"、
* @OA \スキーマ（
*タイプの= "文字列" 
*）
*）、
* @OAレスポンス\（
レスポンス= 200 *、
*説明= "ユーザーオブジェクト"、
* @OA \ JsonContent（REF = "＃/コンポーネント/スキーマ/ UserModel"）
*）
*）
* /

リクエストインターフェイスパラメータ

三つのパラメータによって定義することができ闊歩、path、header、query

  • パス、などendponitパラメータ、の存在下で、/ユーザ/ {USER_ID}
  • ヘッダは、リクエストヘッダパラメータは、ユーザトークン検証トークンとして、あります
  • クエリとしてリクエストURLのリクエストパラメータと、/ユーザー？ニックネーム= {}ニックネーム
1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12
 
/ ** 
 * @OA \のGet（
* @OA \パラメータ（
*名= "のuser_id"、
"パス" =で*、
*必要=真、
*説明= "用户のID"、
* @OA \スキーマ（
*タイプ= "文字列" 
*）
*）
* /

POSTは、一般的に使用されるフォーム提出  application/json 、ユーザの作成などの方法を、

@OA\Post
パス=/users

1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11
 
/**
  *   @OA\RequestBody(
 * @OA\MediaType(
 * mediaType="application/json",
 * @OA\Schema(ref="#/components/schemas/UserModel"),
 * example={
 * "username": "helingfeng", "age": "25"
 * }
 * )
 * )
 */

Schema 模型定义

上面的注释中，多次引用 @OA\Schema(ref="#/components/schemas/UserModel")

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
 
/**
 * @OA\Schema(
 * schema="UserModel",
 * required={"username", "age"},
 * @OA\Property(
 * property="username",
 * type="string",
 * description="用户名称"
 * ),
 * @OA\Property(
 * property="age",
 * type="int",
 * description="年龄"
 * )
 * )
 */

Laravel-Swagger 会自动根据您的注释进行匹配

上传文件接口示例

定义一个接口，接收上传文件，并返回结果远程文件地址

接口定义：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
 
/**
  * @OA\Post(
 * path="/api/files/upload",
 * summary="文件上传",
 * tags={"文件上传"},
 * @OA\RequestBody(
 * @OA\MediaType(
 * mediaType="multipart/form-data",
 * @OA\Schema(
 * required={"upload_file"},
 * @OA\Property(
 * property="upload_file",
 * type="file",
 * description="上传文件"
 * ),
 * ),
 * )
 * ),
 * @OA\Response(
 * response=200,
 * description="上传成功",
 * @OA\JsonContent(ref="#/components/schemas/UploadFileModel")
 * ),
 * @OA\Response(
 * response="default",
 * description="error",
 * @OA\JsonContent(ref="#/components/schemas/ErrorModel")
 * )
 * )
 */

 

模型定义：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
 
/**
 * @OA\Schema(
 * schema="UploadFileModel",
 * @OA\Property(
 * property="file_name",
 * type="string",
 * description="文件名，不包含路径"
 * ),
 * @OA\Property(
 * property="file_path",
 * type="string",
 * description="文件路径"
 * ),
 * @OA\Property(
 * property="file_url",
 * type="string",
 * description="URL链接，用于展示"
 * ),
 * @OA\Property(
 * property="file_size",
 * type="string",
 * description="文件大小，单位B"
 * ),
 * @OA\Property(
 * property="extension",
 * type="string",
 * description="文件扩展名"
 * )
 * )
 */

访问 api/documentation 效果如图

demo1

try it out 上传文件操作结果

demo2

需要权限认证的接口

一般对外网开放的接口，需要添加权限控制，Swagger 提供很好的支持

在 l5-swagger.php 配置文件中添加， crypt-token 定义请求头部必须添加 token 作为权限校验令牌。

1
2
3
4
5
6
7
8
9
10
11
12
13
 
'security' => [
    /*
 |--------------------------------------------------------------------------
 | Examples of Security definitions
 |--------------------------------------------------------------------------
 */
 'crypt-token' => [ // Unique name of security
 'type' => 'apiKey', // The type of the security scheme. Valid values are "basic", "apiKey" or "oauth2".
 'description' => 'A short description for security scheme',
 'name' => 'token', // The name of the header or query parameter to be used.
 'in' => 'header', // The location of the API key. Valid values are "query" or "header".
 ],
]

接口注释中，添加对应的验证方式：

1
2
3
4
5
 
/**
  * security={
 * {"crypt-token": {}}
 * },
 */

demo3

更多 Swagger3 定义字段描述，可以查看官方文档：https://swagger.io/specification/#parameterObject