从零开始系列-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

laravel

本作品采用《CC 协议》，转载必须注明作者和本文链接

编程两年半，喜欢ctrl（唱、跳、rap、篮球）

lixueyuan

课程读者 111 声望

编程两年半，喜欢ctrl（唱、跳、rap、篮球）

1 人点赞

从小程序个人账户申请开始，带你一步步进行开发一个微信小程序，直到提交微信控制台上线发布。

以构建论坛项目 LaraBBS 为线索，展开对 Laravel 框架的全面学习。应用程序架构思路贴近 Laravel 框架的设计哲学。

讨论数量: 1

dongzhiyu

130 声望

确实很不错，就是用JWT ，不安全！容易暴露用户密码，要混淆加密！用passport更好！

3年前评论

讨论应以学习和精进为目的。请勿发布不友善或者负能量的内容，与人为善，比聪明更重要！

帮助

从零开始系列-Laravel编写api服务接口：15.swagger 2.0

简介

社区赞助商

关于 LearnKu

资源推荐

服务提供商

其他信息

从零开始系列-Laravel编写api服务接口：15.swagger 2.0

简介

社区赞助商

关于 LearnKu

资源推荐

服务提供商

其他信息

请登录