Ask a Question

How to add description for each api response data in swagger api doc

fokrule
New Member

How to add description for each api response data in swagger api doc

Hi, I am creating api using Swagger. My api is working fine. Now what I want is, I want to add description for each data that is returning my api. Suppose here is my api functionality.

@SWG\POST(
        path="/api/data",
        tags={"datas"},
        summary="returns all datas",
        description="Base url  is : http://example.com/",
        @SWG\Parameter(
            name="Authorization",
            in="header",
            description="Token to access Audio File",
            required=true,
            type="string",
            default="Bearer TOKEN",
            description="Authorization"
        ),
        @SWG\Response(
            response="200",
            description="Successful operation",
        ),
        @SWG\Response(
            response=400,
            description="Invalid Data| Data not in request"
        ),
        @SWG\Response(
            response=401,
            description="Invalid token | Header Token is missing"
        ),
    )

This api functionlity returning data like this : 

{
  "data": [
    {
      "id": 1,
      "title": "Title of the file",
      "description": "description of file",
      "content": "content name will be here",
      "thumbnail": "content thumbnail will be here"
    }
  ]
}

Now what I want is, I want to add description in the documentation what does id, title, description, content & thumbnail means?  I simple word I want to add little description for those. I have tried adding $ref and  describing responses. But it is not working. Almost every time I am getting error like this failed to parse JSON/YAML response. Please help me on this. Thanks 

cancel
Showing results for 
Search instead for 
Did you mean: