从零开始系列-Laravel编写api服务接口：15.swagger 2.0
220 / 1 / 创建于 2年前
lixueyuan 的个人博客
简介
上面整理的是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 协议》，转载必须注明作者和本文链接
关于 LearnKu
粤公网安备 44030502004330号
推荐文章：