Swagger php 文档注释

swagger php 2.x注释文档Api介绍

/**
 * @SWG\Swagger(
 *     @SWG\Info(
 *         version="1.0.0",
 *         title="Youxuana",
 *           description="This is description",
 *           termsOfService="http://swagger.io/terms/",
 *         @SWG\License(
 *                name="License",
 *                url="http://www.apache.org/licenses/LICENSE-2.0.html",
 *                ),
 *         @SWG\Contact(
 *                name="Youxuana",
 *                 url="http://www.youxuana.com",            
 *                 email="123@youxuana.com"            
 *            )
 *     ),
 *        @SWG\ExternalDocumentation(
 *            description="External Documentation",
 *            url="http://youxuana.com",
 *        ),
 *     host="/test/slim",
 *     basePath="/v1",
 *     schemes={"http"},
 *     consumes={"application/json"},
 *     produces={"application/json"},
 * ),
 */

控制器注释

/**
* @SWG\Get(
*     tags={"domains"},
*     path="/domains/{domainId}",
*     summary="Get a domain by domainId",
*     description="Muliple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.",
*     operationId="getDomainByDomainId",
*     produces={"application/json"},
*     @SWG\Parameter(
*         name="domainId",
*         in="path",
*         description="Get a domain by domainId",
*         required=true,
*         type="string",
*         collectionFormat="multi"
*     ),
*     @SWG\Response(
*         response=200,
*         description="successful operation",
*         @SWG\Schema(ref="#/definitions/Domain_Get"),
*     ),
*     @SWG\Response(
*         response="400",
*         description="Invalid tag value",
*     ),
* )
*/
function get_domain_info($request,$response,$args){
     $res = model_get_domain_info($args);
     if($res->code == 200){
          return $response->withJson($res->data,$res->code);
     }else{
          $tips = new stdclass();
          $tips->code = $res->sub_code;
          $tips->message = $res->message;
          return $response->withJson($tips,$res->code);
     }
    
}

/**
* @SWG\Post(
*    tags={"domains"},
*    path="/domains",
*    summary="Post a domain summary",
*    description="Post a domain description",
*    operationId="postADomain",
*    produces={"application/json"},
*    @SWG\Parameter(
*         name="domainAvatar",
*         in="body",
*         description="Post a domain avatar",
*         required=true,
*         @SWG\Schema(ref="#/definitions/Domain_Get"),
*    ),
*     @SWG\Response(
*         response=200,
*         description="successful operation",
*         @SWG\Schema(ref="#/definitions/Domain_Get"),
*     ),
*     @SWG\Response(
*         response="400",
*         description="Invalid tag value",
*     ),
*)
*/
function domain_add($req,$res){
     var_dump($req->getParsedBody());die;
}

Model注释

/**
 * @SWG\Definition(
 *   type="object",
 *   @SWG\Xml(name="Domain_Get")
 * )
 */
class Domain_Get{
     /**
     * @SWG\Property(type="string", example="youxuana", description="Valid Value:a-z, A-Z, 0-9, “_”,“-”,“.”,“@”; Notes:domainId(Unique Identifier)")
     */
     public $domainId;
     /**
     *    @SWG\Property(
     *        ref="#/definitions/Domain_Address",    
     *)
     */
     public $address;
      /**
     *    @SWG\Property(
     *        type="array",
     *        @SWG\Items(ref="#/definitions/Domain_User")    
     *)
     */
     public $users;
}
/**
* @SWG\Definition(
*     type="object",
*    @SWG\Xml(name="Domain_Address")
*)
*/
class Domain_Address{
     /**
     * @SWG\Property( example="北京", description="Valid Value:a-z, A-Z, 0-9, “_”,“-”,“.”,“@”; Notes:domainId(Unique Identifier)")
     * @var string
     */
     public $city;
}
/**
* @SWG\Definition(
*    type="object",
*    @SWG\Xml(name="Domain_User")            
*)
*/
class Domain_User{
     /**
     * @SWG\Property(type="string", example="赵老师", description="Valid Value:a-z, A-Z, 0-9, “_”,“-”,“.”,“@”; Notes:domainId(Unique Identifier)")
     */
     public $name;
}
function model_get_domain_info($data){
    global $dbm;
    $tips = new stdclass();
    $sql = "SELECT * FROM taclgroupstable WHERE FCompanyAccountID = '".$data['domainId']."'";
    $res = $dbm->query($sql)->fetch(PDO::FETCH_ASSOC);
    if($res){
        $tips->code = 200;
        $tips->data = (object) $res;
    }else{
        $tips->code = 405;
        $tips->sub_code = 1101;
        $tips->message = "DomainId not exist";
        return $tips;
    }
    return $tips;
}