phpDocumentor 2에서 JSON 매개 변수와 반환 값을 어떻게 문서화해야합니까?

Question

프로젝트의 일부로 CakePHP로 작성된 PHP REST API가 있습니다. 모든 API 엔드 포인트는 컨트롤러에 개별 메소드로 존재하며 JSON 문자열에 인수와 리턴 값을 허용합니다. phpDocumentor2 이러한 메서드에 대한 매개 변수 및 반환 형식을 문서화하는 방법을 그림하려고합니다. 내가 UsersController의 편집() 메소드가있는 경우 예를 들어

는 골격 사용자 모델에 대한 업데이트 지정된 필드 (나는 간결에 대한 코드를 단순화했습니다)이 같다고 :

public function edit() { 
    //Get arguments 
    $args = $this->request->data['args']; 
    $id = $args['id']; 

    //Perform processing 
    if (!$this->User->exists($id)) { 
     $data = $this->createError(300); 
    } 
    else { 
     $this->User->id = $id; 

     $saveData = array(); 

     if (isset([$args['first_name'])) { 
      $saveData['User']['first_name'] = $args['first_name']; 
     } 

     if (isset([$args['last_name'])) { 
      $saveData['User']['last_name'] = $args['last_name']; 
     } 

     $isSaved = $this->User->save($saveData); 

     if (count($this->User->validationErrors) > 0) { 
      $data = $this->createError(202, $this->User->validationErrors); 
     } 
     else { 
      $data = array('status' => $isSaved ? 1 : 0); 
     } 
    } 

    //Output data 
    return $data; 
} 

I을 사용자의 이름과 성 :

{ 
    "id": 1 
    "first_name": "John" 
    "last_name": "Doe" 
} 

API 호출이 성공하면 수정하려면 다음 JSON에 요청을 보낼 수 있습니다, 방법은 반환합니다

{ 
    "status": 1 
} 

그리고 그것은 실패 할 경우, 아마도 실패 데이터 유효성 검사로 인해, 뭔가를 반환 할 수 있습니다 방법 :

{ 
    "status": 0 
    "code": 202, 
    "messages": { 
     "first_name": { 
      "Numeric characters are not allowed." 
     } 
    } 
} 

내가 반환 값과 매개 변수를 각각 기록하기 phpDocumentor의 @return 및 @param을 사용할 수 있음을 이해 문서에서 JSON 반환에 대한 언급은 없습니다.

나는 예를 들어,

@return $value string A JSON string that contains the status code and error messages if applicable. 

으로 반환 형식을 문서화 할 수 그러나 나는 거의 특히 "취득을 위해 (뭔가 비슷한 트위터의 상태/user_timeline 상상), 특히 더 복잡한 데이터 구조를 포함하는 반환을위한, 그 적절한 고려하지 "및"보기 "API 메소드를 제공합니다.

@param string $id The ID of the user to be updated. 
@param string $first_name optional The first name of the user. 
@param string $last_name optional The last name of the user. 

: 한편

는 매개 변수에 대해, 나는 나를 (한 JSON 문자열에 싸여 모든 매개 변수를 고려) 각 매개 변수에 대한 한 줄을 작성하는 것이 같은 맞는지 확실하지 않다

phpDocumentor가 이러한 요구를 충족시킬 수 없다면 다른 옵션을 탐색 할 수 있습니다.

Answer 1

여기서는 내가 가지고있는 JSON 문자열에 대해 구조 요소 정의을 추가로 제공 할 수있는 구문을 알지 못합니다. 나는 기본적인 생각을 다룰 수 있습니다.

edit()에 명시적인 인수가 전달되지 않으므로 어쨌든 @param 태그를 사용하면 안됩니다. 아마도 $ data 배열이 $ data의 [ 'args'] 키에있는 "edit()에 대한 인수"를 찾는 방법을 설명하는 설명과 함께 "@ users UserController :: $ request"를 포함 할 수도 있습니다. [ 'args']와 그 구조에 관한 필요한 정보를 설명하는 것은 순수 텍스트 설명이어야합니다. 여기에 일종의 "구조화 된 문서 레이아웃"이있는 것은 아닙니다.그러한 doc 요소는 1) 다른 문서로부터 연결될 수 있고, 2) 요소를 표시 할 때 문서 레이아웃 형식에 영향을 미칩니다. 내가 편집()를위한 docblock에, 이런 식으로 접근하는 것 같아요 실제 수익률이 아니라 여기에 있기 때문에, 반환으로

* @uses UserController::$request 
*   $request has its own $data array, whose ['args'] key 
*   should contain a JSON value. In the JSON, keys represent 
*   the fields to edit, values are the new values. 

단지 배후 수정이 이루어지고, I

* @return string JSON that indicates success/failure of the update, 
*    or JSON that indicates an error occurred. 

당신은 확실히 문서가 텍스트 만이 아닌 실제 JSON 같은 JSON을 렌더링 할 수있는 제외하고 각 지점에서 JSON 문자열의 예를 표시하여이를 확장 할 수 있지만 : 진정한 @return 태그를 사용합니다 , 나는 너가 뭘 할 수 있는지 다른 것을 알지 못한다. 저는 상태 반환 JSON 예제를 docblock의 자세한 설명에 표시하도록 선택할 것이고, 태그에 모든 내용을 넣으 려하지 않고 JSON 레이아웃을 보려면 createError() 메서드에 대한 문서를 독자에게 참조하십시오. 당신은 다음과 같이 느낄 수

/** 
* edit() method 
* 
* The edit() method examines values already set elsewhere, acts on the edits requested 
* by those values, and returns an indication of whether or not the edits succeeded. 
* 
* An array key of $data['args'] must be set in the UserController::$request object. 
* It must contain a JSON string that lists the fields to update and the values to use. 
* 
* Example: 
* <code> 
* { 
*  "id": 1 
*  "first_name": "John" 
*  "last_name": "Doe" 
* } 
* </code> 
* 
* "id" is required, while other fields are optional. 
* 
* The JSON string that is returned by edit() will normally indicate whether or not 
* the edits were performed successfully. 
* 
* Success: 
* <code> 
* { 
*  "status": 1 
* } 
* </code> 
* Failure: 
* <code> 
* { 
*  "status": 0 
* } 
* </code> 
* 
* In the case of validation errors with the values used in the updates, 
* a JSON error string would be returned, in the format generated 
* by the createError() method. 
* 
* @return string JSON that indicates success/failure of the update, 
*    or JSON that indicates an error occurred. 
* 
* @uses UserController::$request 
* @see UserController::createError() 
*/ 

은 많은 거기에 넣어,하지만 당신은 당신이 문서를 읽는 것 코더/소비자에게 어떤 무대 뒤의 부두를 설명하기 위해 노력하고 있음을 이해해야한다. 직접적인 인수를 사용하여 메소드를 호출하는 대신 사용자가 로터리 방식으로 인수를 제공해야하는 방법을 설명해야합니다. 자세한 설명의 상세한 표시는 edit() 메서드를 올바르게 사용하는 방법을 이해하지 못하는 것처럼 사용자가 느끼지 못하게하는 데 큰 도움이됩니다.

Answer 2

본인의 요구 사항은 귀하의 코드가 문서화 된 것보다 귀하의 API에 대한 문서화가 필요합니다. API 문서의 경우 PHPDocumentor와 같은 도구를 사용하지 않고 특정 도구를 사용할 수 있습니다. 나는 API 문서에 대한 apiary.io을 사용하고, 여기

http://docs.dollyaswinnet.apiary.io/

이 같은 많은 도구가 있습니다 내

의 샘플을, 그리고 일반적으로 그들은 상업 있습니다. 전에는 아직 무료이기 때문에 나는 apiary.io를 선택합니다.