簡介
上面整理的是swagger 3.0。
之前一直用的swagger2.0,下面就詳細說一下swagger2.0的用法關於laravel 版本對應的swagger可以訪問官網檢視
github.com/DarkaOnLine/L5-Swagger/...
就是 laravel8.x 版本只支援swagger3.0。
不多說了，直接貼程式碼吧，可以直接用：
// 定義文件基本資訊
/**
* @SWG\Swagger(
* basePath="/api/",
* schemes={"http", "https"},
* consumes={"application/json","application/xml"},
* produces={"application/json","application/xml"},
* host="yxhospital.local",
* @SWG\Info(
* version="1.0.0",
* title="xx介面系統",
* description="描述。。。描述",
* @SWG\Contact(
* email="aaaa"
* ),
* ),
* @SWG\TAG(
* name="User",
* description="使用者介面"
* ),
* @SWG\TAG(
* name="Doctor",
* description="醫生介面",
* ),
* @SWG\TAG(
* name="Hospital",
* description="醫院介面",
* ),
* )
*/
/**
* @SWG\SecurityScheme(
* securityDefinition="passport",
* type="oauth2",
* tokenUrl="/api/login",
* flow="password",
* scopes={}
* )
*/
// 定義通用422錯誤
/**
* @SWG\Definition(
* definition="422",
* @SWG\Property(
* property="status_code",
* type="integer",
* example=422,
* description="錯誤碼",
* ),
* @SWG\Property(
* property="message",
* type="string",
* example="xx驗證錯誤",
* description="錯誤描述",
*
* )
* )
*
*/
// 定義醫院token
/**
* @SWG\Parameter(
* parameter="HospitalToken",
* name="Authorization",
* type="string",
* in="header",
* required=true,
* default="Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOi8vaG9zcGl0YWwudGVzdC9hcGkvbG9naW4iLCJpYXQiOjE1ODMxMzc4MDcsImV4cCI6MTU5MDkxMzgwNywibmJmIjoxNTgzMTM3ODA3LCJqdGkiOiI2UWxSMnlwSVJPQUYxbHdmIiwic3ViIjoxLCJwcnYiOiJiMTUwYmM0NTEzYjk1OTRmMTljNDFlNWIyMDY1YWM5NDA4ZjNhNThlIiwiZ3VhcmRfdHlwZSI6Imhvc3BpdGFsIn0.mmPE1MnnozovELKrUv-2E5no4QUDNf8i6liiAKrY5dY"
* )
*/
// 醫生端token
/**
* @SWG\Parameter(
* parameter="DoctorToken",
* name="Authorization",
* type="string",
* in="header",
* required=true,
* default="Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOi8veXhob3NwaXRhbC5sb2NhbC9hcGkvbG9naW4iLCJpYXQiOjE1ODQ1MDA0NDQsImV4cCI6MTU5MjI3NjQ0NCwibmJmIjoxNTg0NTAwNDQ0LCJqdGkiOiJQYmtFWW5PR0NnUnVYZ1ZoIiwic3ViIjo4LCJwcnYiOiJlMTQ3ODdhYWI2NjY4OGNlMDZjNDcxMmU2NzNlMWExYzQ0ZjQ5MDk0IiwiZ3VhcmRfdHlwZSI6ImRvY3RvciJ9.iV8gItmly1yBspgkuQ-Z8KPuHXiw1PgehnJgce3xDHc"
* )
*/
// 定義一個通用的資訊返回
/**
* @SWG\Definition(
* definition="submerchantInfo",
* type="object",
* required={""},
* example={"id":1,"organ_id":2,"sub_appid":"wx123we","sub_mch_id":"d32112","created_at":"2020-12-12 12:12:12","updated_at":"2020-12-12 12:12:12"},
* @SWG\Property(property="id",type="integer",example="1",description="自增id"),
* @SWG\Property(property="organ_id",type="integer",example="1",description="藥店id"),
* @SWG\Property(property="sub_appid",type="string",example="wx993212312877",description="微信子商戶appid",),
* @SWG\Property(property="sub_mch_id",type="string",example="d97fe11232112jjv39212==",description="微信子商戶mch_id",),
* @SWG\Property(property="created_at",type="string",example="2020-01-15 13:22:57",description="新增時間",),
* @SWG\Property(property="updated_at",type="string",example="2020-01-15 13:22:57",description="更新時間",)
* )
*/
/**
* @SWG\Get(
* path="/hospital/submerchant/{id}",
* operationId="getProjectById",
* tags={"Hospital"},
* summary="獲取子商戶的資訊詳情",
* description="獲取子商戶的appid和商戶號",
* @SWG\Parameter(name="id",description="organ_id藥店的id號",required=true,type="integer",in="path"),
* @SWG\Parameter(ref="#/parameters/HospitalToken"),
* @SWG\Response(response=200,description="successful operation",
* @SWG\Definition(definition="",type="object",ref="#/definitions/submerchantInfo")),
* @SWG\Response(response=400, description="Bad request"),
* @SWG\Response(response=404, description="Resource Not Found")
* )
*
*/
/**
* @SWG\Post(
* path="/hospital/submerchant",
* summary="新增子商戶微信配置資訊",
* tags={"Hospital"},
* consumes={"application/x-www-form-urlencoded"},
* description="Adds a new person to the persons list.",
* @SWG\Parameter(ref="#/parameters/HospitalToken"),
* @SWG\Parameter(name="sub_appid",in="formData",type="string",required=true,description="微信的appid",default="wx102312987681122"),
* @SWG\Parameter(name="sub_mch_id",in="formData",type="string",required=true,description="微信的mch_id",default="xxx"),
* @SWG\Response(response="200",description="succesfully created.",@SWG\Schema(ref="#/definitions/submerchantInfo")),
* @SWG\Response(response="422",description="Persons couldn't have been created.",@SWG\Schema(ref="#/definitions/422"))
* )
*/
/**
* @SWG\Put(
* path="/hospital/submerchant/{id}",
* summary="修改子商戶微信配置資訊",
* tags={"Hospital"},
* description="修改子商戶",
* @SWG\Parameter(name="id",in="path",default=1,required=true,type="integer",description="子賬號id"),
* @SWG\Parameter(ref="#/parameters/HospitalToken"),
* @SWG\Parameter(name="sub_appid",type="string",in="formData",required=true,description="子商戶院appid",),
* @SWG\Parameter(name="sub_mch_id",type="string",in="formData",required=true,description="子商戶mch_id",),
* @SWG\Response(response="200",description="Persons succesfully created.",@SWG\Schema(ref="#/definitions/submerchantInfo")),
* @SWG\Response(response="422",description="Persons couldn't have been created.",@SWG\Schema(ref="#/definitions/422"),)
* )
*/
/**
* @SWG\Delete(
* path="/hospital/submerchant/{id}",
* summary="刪除一個商戶資訊",
* tags={"Hospital"},
* description="返回包含所有人的列表。",
* @SWG\Parameter(ref="#/parameters/HospitalToken"),
* @SWG\Parameter(name="id",in="path",type="integer",required=true,description="要刪除的子商戶id",),
* @SWG\Response(response=204,description="刪除成功",),
* )
*/
/**
* @SWG\Get(
* path="/doctor/duty",
*
* operationId="getDutyIndex",
* tags={"Doctor"},
* summary="檢視排班表",
* description="醫生端內部的排班表",
* @SWG\Parameter(ref="#/parameters/DoctorToken"),
* @SWG\Response(response=200,description="123",@SWG\Schema(ref="#/definitions/DoctorDuty")),
* @SWG\Response(response=400, description="Bad request"),
* @SWG\Response(response=404, description="Resource Not Found")
* )
*
* // 返回列表
* @SWG\Definition(
* definition="DoctorDuty",
* type="object",
* required={""},
* example={
"data": {
{
"id": 1,
"week_name": "週一",
"created_at": null,
"updated_at": null,
"days": {
{
"id": 1,
"work_period": "上午8~12點",
"parent_id": 1,
"type": 1,
"created_at": null,
"updated_at": null
}}}}},
* @SWG\Property(property="id",type="integer",example="1",description="自增id"),
* @SWG\Property(property="week_name",type="integer",example="週一",description="藥店id"),
* @SWG\Property(property="days",type="array",example="",description="每週下面的具體排期",
* @SWG\Items(
* @SWG\Property(property="type",type="integer",example="1",description="1表示工作時間2表示下班時間3表示任何時間"),
* @SWG\Property(property="work_period",type="integer",example="1",description="描述上下班時間"),
* @SWG\Property(property="parent_id",type="integer",example="1",description="周id"),
* @SWG\Property(property="created_at",type="string",example="2020-01-15 13:22:57",description="新增時間"),
* @SWG\Property(property="updated_at",type="string",example="2020-01-15 13:22:57",description="更新時間"),
* )),
* @SWG\Property(property="created_at",type="string",example="2020-01-15 13:22:57",description="新增時間"),
* @SWG\Property(property="updated_at",type="string",example="2020-01-15 13:22:57",description="更新時間")
* )
*/
/**
* @SWG\GET(
* path="/doctor/doctor_duty",
* operationId="getDoctorDutyIndex",
* tags={"Doctor"},
* summary="檢視醫生排班表",
* description="醫生端某個醫生（我）的內部的排班表跟排班表返回格式一樣但是返回我選擇的",
* @SWG\Parameter(ref="#/parameters/DoctorToken"),
* @SWG\Response(response=200,description="123",@SWG\Schema(ref="#/definitions/DoctorDuty")),
* @SWG\Response(response=400, description="Bad request"),
* @SWG\Response(response=404, description="Resource Not Found")
* )
**/
/**
* @SWG\Post(
* path="/doctor/doctor_duty",
* summary="設定時間段",
* tags={"Doctor"},
* consumes={"application/x-www-form-urlencoded"},
* description="Adds a new person to the persons list.",
* @SWG\Parameter(ref="#/parameters/DoctorToken"),
* @SWG\Parameter(in="formData",type="array", name="duty_day_ids[]",collectionFormat="multi",@SWG\items(type="integer")),
* @SWG\Response(response="422",description="err.",@SWG\Schema(ref="#/definitions/422")),
* @SWG\Response(response="204",description="Persons couldn't have been created.")
* )
**/
/**
* @SWG\Get(
* path="doctor_duty/{id}",
* summary="檢視某一天的排班表",
* tags={"Doctor"},
* consumes={"application/x-www-form-urlencoded"},
* description="檢視某一天的排班表",
* @SWG\Parameter(ref="#/parameters/DoctorToken"),
* @SWG\Parameter(name="id",in="path",default=1,required=true,type="integer",description="周的id"),
* @SWG\Parameter(ref="#/parameters/DoctorToken"),
* @SWG\Parameter(in="query",type="string", name="include"),
* @SWG\Response(response="200",description="返回一週的某一天詳情",@SWG\Schema(ref="#/definitions/DutyWeekDetail")),
* @SWG\Response(response="422",description="err.",@SWG\Schema(ref="#/definitions/422")),
* @SWG\Response(response="204",description="Persons couldn't have been created.")
* )
*
* @SWG\Definition(
* definition="DutyWeekDetail",
* type="object",
* required={""},
* example={"id":1,"organ_id":2,"sub_appid":"wx123we","sub_mch_id":"d32112","created_at":"2020-12-12 12:12:12","updated_at":"2020-12-12 12:12:12"},
* @SWG\Property(property="id",type="integer",example="1",description="自增id"),
* @SWG\Property(property="organ_id",type="integer",example="1",description="藥店id"),
* @SWG\Property(property="sub_appid",type="string",example="wx993212312877",description="微信子商戶appid",),
* @SWG\Property(property="sub_mch_id",type="string",example="d97fe11232112jjv39212==",description="微信子商戶mch_id",),
* @SWG\Property(property="created_at",type="string",example="2020-01-15 13:22:57",description="新增時間",),
* @SWG\Property(property="updated_at",type="string",example="2020-01-15 13:22:57",description="更新時間",)
* )
*/
安裝好後直接將以上註解複製到專案中訪問對應網址就可以了（不會有人手寫註解吧不會吧不會吧）
訪問的預設地址為：
http://{url}/api/documentation
本作品採用《CC 協議》，轉載必須註明作者和本文連結