從零開始系列-Laravel編寫api服務介面：15.swagger 2.0

lixueyuan發表於2021-05-18
LaravelAPISwagger
系列文章：
從零開始系列-Laravel編寫api服務介面：1.安裝Laravel 從零開始系列-Laravel編寫api服務介面：2.Dingo封裝 從零開始系列-Laravel編寫api服務介面：3.JWT多使用者訪問 從零開始系列-Laravel編寫api服務介面：4.Migration 和 Seed 從零開始系列-Laravel編寫api服務介面：5.中介軟體驗證JWT登陸 從零開始系列-Laravel編寫api服務介面：6.資料庫查詢（未完待續） 從零開始系列-Laravel編寫api服務介面：7.資料庫新增和更新（未完待續） 從零開始系列-Laravel編寫api服務介面：8.整合微信包-LaravelWechat的使用 從零開始系列-Laravel編寫api服務介面：9.整合簡訊包 從零開始系列-Laravel編寫api服務介面：10.transformer 從零開始系列-Laravel編寫api服務介面：11.自定義包 從零開始系列-Laravel編寫api服務介面：12.編寫swagger3.0 API文件 從零開始系列-Laravel編寫api服務介面：13.後端上傳七牛雲 從零開始系列-Laravel編寫api服務介面：14.計劃任務和佇列 從零開始系列-Laravel編寫api服務介面：15.swagger 2.0

簡介

上面整理的是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 協議》，轉載必須註明作者和本文連結
程式設計兩年半，喜歡ctrl（唱、跳、rap、籃球）

相關文章