I am using laravel 5.2.* and i am using darkaonline/l5-swagger : ~3.0 for the API's Documentation. I am sending parameters in header body and when I see the Swagger UI its shows me like below.
Data Type undefined
See below image for more details.
/**
* #SWG\Post(
* path="/api/v1/compaign_attr",
* summary="List compaign attributes",
* #SWG\Parameter(
* name="campaign_id",
* in="body",
* description="ID to fetch the targeted compaigns",
* required=true,
* #SWG\Property(property="request", type="json", example={ "campaign_id": 818, "code":"PLATFORM", "type":"Message"} )
* ),
* #SWG\Parameter(
* name="x-api-key",
* in="header",
* description="api key validation",
* required=true,
* type="string",
* ),
* #SWG\Response(response=200, description="successful operation", #SWG\Property(property="result", type="json", example={ "aa": { "bb", "cc" } } )),
* #SWG\Response(response=401, description="not authorized"),
* #SWG\Response(response=500, description="internal server error")
* )
*
*/
L5-Swagger does not have data type json. You need to set your parameter schema as object through swagger definition or inline schema.
* #SWG\Parameter(
* in="body",
* name="body",
* required=true,
* description="ID to fetch the targeted campaigns.",
* #SWG\Schema(
* #SWG\Property(property="campaign_id", type="integer", example=818),
* #SWG\Property(property="code", type="string", example="PLATFORM"),
* #SWG\Property(property="type", type="string", example="Message")
* ),
* )
This his how it looks.
Related
I have this a project that is using Laravel for the api and swagger for documentation
I have this method in my login controller:
/**
* Handle an incoming authentication request.
*
*
* #OA\Post(
* tags={"UnAuthorize"},
* path="/login",
* summary="User Login",
* #OA\RequestBody(
* #OA\MediaType(
* mediaType="application/json",
* #OA\Schema(
* type="object",
* ref="#/components/schemas/LoginRequest",
* )
* )
* ),
* #OA\Response(
* response="200",
* description="An example resource",
* #OA\JsonContent(
* type="object",
* #OA\Property(
* format="string",
* default="20d338931e8d6bd9466edeba78ea7dce7c7bc01aa5cc5b4735691c50a2fe3228",
* description="token",
* property="token"
* )
* ),
* #OA\JsonContent(ref="#/components/schemas/UserResource")
* ),
* #OA\Response(response="401", description="fail"),
* )
*
* #param \App\Http\Requests\Auth\LoginRequest $request
* #return \Illuminate\Http\JsonResponse
*/
public function store(LoginRequest $request)
{
$request->authenticate();
return response()->json(
[
"token" => $request->user()->createToken($request->email)->plainTextToken,
"user" => $request->user();
]
);
}
then, when I run this command: php artisan l5-swagger:generate ,it displays this error:
c:\myproject\vendor\zircote\swagger-php\src\Logger.php:40
36▕ $this->log = function ($entry, $type) {
37▕ if ($entry instanceof Exception) {
38▕ $entry = $entry->getMessage();
39▕ } ➜ 40▕ trigger_error($entry, $type);
41▕ };
42▕ }
When I remove this
#OA\JsonContent(ref="#/components/schemas/UserResource")
it works, but the user data is not displayed, maybe I should only return the token, and make another request with the token to get the information about the logged user. What can I do?, thanks
EDIT:
#OA\Response(
* response="200",
* description="An example resource",
* #OA\JsonContent(
* type="object",
* #OA\Property(
* format="string",
* default="20d338931e8d6bd9466edeba78ea7dce7c7bc01aa5cc5b4735691c50a2fe3228",
* description="token",
* property="token"
* ),
* #OA\Property(
* format="application/json",
* property="user",
* #OA\JsonContent(ref="#/components/schemas/UserResource")
* )
* ),
* )
I tried this, but it shows errors
Pretty close except...
use of 'format' instead of 'type'
you do not have to specify the content type if your property is already wrapped in #OA\JsonContent
you need to be careful with surplus trailing ','; doctrine can be picky with that
Here is my take which does work stand-alone (except for the missing #OA\Info):
<?php
use OpenApi\Annotations\OpenApi as OA;
/**
* #OA\Schema
*/
class LoginRequest{}
/**
* #OA\Schema
*/
class UserResource{}
/**
* Handle an incoming authentication request.
*
*
* #OA\Post(
* tags={"UnAuthorize"},
* path="/login",
* summary="User Login",
* #OA\RequestBody(
* #OA\MediaType(
* mediaType="application/json",
* #OA\Schema(
* type="object",
* ref="#/components/schemas/LoginRequest"
* )
* )
* ),
* #OA\Response(
* response="200",
* description="An example resource",
* #OA\JsonContent(
* type="object",
* #OA\Property(
* type="string",
* default="20d338931e8d6bd9466edeba78ea7dce7c7bc01aa5cc5b4735691c50a2fe3228",
* description="token",
* property="token"
* ),
* #OA\Property(
* property="user",
* ref="#/components/schemas/UserResource"
* )
* )
* ),
* #OA\Response(response="401", description="fail")
* )
*
*/
class Controller {}
The JsonContent you removed should be a property on the first JsonContent I think
I'm using Swagger to do the documentation of the Laravel API's, and sometimes there is also testing apart from POSTMAN, the issue is that the GET methods with parameters do not work Route::get('/searchProduct/{id}','Api\ReportController#getProductsByID');
But if the GET method does not have parameters it works perfectly. In Swagger I realized that when I make the query I don't enter the parameter in {id} but I believe after {id}?id=4
This is my route
My route
Route::get('/searchProduct/{id}','Api\ReportController#getProductsByID');
Result in Swagger
www.x.cl/api/searchProduct/{id}?id=4 //ERROR
How it should work
www.x.cl/api/searchProduct/4
Because in POSTMAN I only change my ID by the number and the search works for me.
This is my controller
/**
* #OA\Get(
* path="/api/searchProduct/{id}",
* summary="Search Product by Status",
* description="Lorem ipsun",
* security={
* {"bearer_token":{}},
* },
* #OA\Parameter(
* name="id",
* in="query",
* description="Buscar por estado",
* required=true,
* ),
* #OA\Response(
* response=200,
* description="OK",
* #OA\MediaType(
* mediaType="application/json",
* )
* ),
* #OA\Response(
* response="default",
* description="Ha ocurrido un error."
* ),
* #OA\Response(
* response="401",
* description="No se ha autenticado, ingrese el token."
* ),
* )
*/
public function getProductsByID($uuid){
$validated = Product::status($uuid);
return ReportResource::collection($validated);
}
Try replacing in="query", with in="path", here :
* #OA\Parameter(
* name="id",
* in="query",
* description="Buscar por estado",
* required=true,
* ),
Query refers to "query string", the set of ampersand-separated key/value pairs that come after ? in the URL.
I want to uplaod a file in swagger-php in the json requestBody How can upload with the help of swagger anonations
Trying from lot of hours but not luck how can send and file in application/json array Can you help if any information about this so then i will solve my problem i have not concept about this
when this code generate in the terminal also not have any error and not shown in the request body in the swagger ui
/**
* #OA\Post(
* path="/products/save",
* tags={"Product"},
* summary="Post bulk products",
* description="Return bulk products",
* #OA\RequestBody(
* required=true,
* description="Bulk products Body",
* #OA\JsonContent(
* #OA\Property(
* property="products",
* #OA\Items(
* #OA\Property(property="first_name", type="string"),
* #OA\Property(property="last_name", type="string"),
* #OA\Property(property="email", type="string"),
* #OA\Property(property="phone", type="string"),
* #OA\Property(property="resume", type="string", format="base64"),
* ),
* )
* )
* ),
* )
*/
I want to this type of swagger-ui body so that user can fill attribut and
the resume add in base64 format
{
"products": [
{
"first_name": "string",
"last_name": "string",
"email": "string",
"phone": "string",
"resume": "string" ==> here i will send base64 format of resume file
}
]
}
``
You may use #OA\Property(property="file", type="string", format="binary"), to define a file property:
/**
* #OA\Schema(
* schema="ProductRequest",
* required={"products"},
* #OA\Property(
* property="products",
* type="array",
* #OA\Items(
* #OA\Property(property="first_name", type="string"),
* #OA\Property(property="last_name", type="string"),
* #OA\Property(property="email", type="string"),
* #OA\Property(property="phone", type="string"),
* #OA\Property(property="resume", type="string", format="binary"),
* ),
* )
* )
*/
Then you have to set a media type on your RequestBody using #OA\MediaType:
/**
* #OA\RequestBody(
* request="Product",
* required=true,
* description="Bulk products Body",
* #OA\MediaType(
* mediaType="multipart/form-data",
* #OA\Schema(ref="#/components/schemas/ProductRequest")
* )
* )
*/
And finally on your #OA\Post:
/**
* #OA\Post(
* path="/products/save",
* tags={"Product"},
* summary="Post bulk products",
* description="Return bulk products",
* #OA\RequestBody(ref="#/components/requestBodies/Product"),
* #OA\Response(response=200, ref="#/components/responses/Product")
* )
*/
See also Swagger docs on File data type and File upload for more info.
Update: If you don't want separate declarations just merge them like this:
/**
* #OA\Post(
* path="/products/save",
* tags={"Product"},
* summary="Post bulk products",
* description="Return bulk products",
* #OA\RequestBody(
* required=true,
* description="Bulk products Body",
* #OA\MediaType(
* mediaType="multipart/form-data",
* #OA\Schema(
* #OA\Property(
* property="products",
* type="array",
* #OA\Items(
* #OA\Property(property="first_name", type="string"),
* #OA\Property(property="last_name", type="string"),
* #OA\Property(property="email", type="string"),
* #OA\Property(property="phone", type="string"),
* #OA\Property(property="resume", type="string", format="binary"),
* )
* )
* )
* )
* )
* )
*/
You may also want an approach with PHP classes
So you can define a model like that:
/**
* #OA\Schema(
* schema="User",
* required={"first_name", "last_name" // and so on}
* )
*/
class User
{
/**
* #OA\Property(type="string")
*/
public $first_name;
/**
* #OA\Property(type="string")
*/
public $last_name;
// add your other fields bellow
}
after you can define for example the body of a POST request as follows:
<?php
/**
* #OA\Schema(
* schema="CreateUsers",
* required={"users"}
* )
*/
class CreateUsers
{
/**
* #var array
* #OA\Property(ref="#/components/schemas/User")
*/
public $users;
}
And lastly create the your Request in your documentation for example:
/**
* #OA\Post(
* path="YOUR ROUTE URL",
* operationId="createUsers",
* tags={"Users"},
* #OA\RequestBody(
* required=true,
* #OA\MediaType(
* mediaType="application/json",
* #OA\Schema(ref="#/components/schemas/CreateUsers")
* )
* ),
* summary="Create a collection of users",
* description="Create a collection of users"
* )
**/
EDIT 1:
If you want a request that have a file to the request body you way do:
/**
* #OA\Post(
* path="YOUR ROUTE URL",
* operationId="createUsers",
* tags={"Users"},
* #OA\RequestBody(
* required=true,
* #OA\MediaType(
* mediaType="multipart/form-data", // here we need to change from "application/json" to "multipart/form-data" in order to make our file visible
* #OA\Schema(ref="#/components/schemas/CreateUsers")
* )
* ),
* summary="Create a collection of users",
* description="Create a collection of users"
* )
**/
And make your field in your PHP class:
/**
* #OA\Schema(
* schema="User",
* required={"first_name", "last_name", "file" // and so on}
* )
*/
class User
{
/**
* #OA\Property(type="string")
*/
public $first_name;
/**
* #OA\Property(type="string")
*/
public $last_name;
/**
* #OA\Property(description="file to upload", type="string", format="file")
*/
public $file;
// add your other fields bellow
}
You can see an example here: swagger-php/Examples/petstore.swagger.io/controllers/PetController.php
I am new to Swagger. I am using DarkaOnline Swagger UI (OAS3).
I have a JSON request body like this
{
"CurrentPuzzle": "1",
"OpenedLevel": "10",
"RewardPuzzlePiecess":
[
1,
2,
]
}
I need to define this in swagger model. What I tried so far is I defined the following in swagger controller :
/**
* #OA\Post(path="/gameData",
* tags={"user"},
* summary="Add Game Data of User",
* security={{"bearerAuth":{}}}, *
* description="",
* operationId="gameData",
* #OA\RequestBody(
* required=true,
* description="Created user object",
* #OA\JsonContent(
* type="object",
* #OA\Items(ref="#/components/schemas/Game")
* )
* ),
* #OA\Response(response="default", description="successful operation")
* )
*/
public function gameData()
{
}
In Game Model :
/**
* #OA\Property(
* type="object",
* #OA\Items(
* #OA\Property(
* type="integer",
* description="The puzzle",
* #OA\Schema(type="array")
* ),
* #OA\Property(
* type="integer",
* description="The level",
* #OA\Schema(type="integer")
* ),
* #OA\Property(
* type="array",
* description="The survey ID",
* #OA\Items(
* type="string",
* ),
* #OA\Schema(type="array")
* ),
* ),
* description="Store User Survey Results"
* )
* #var array
*/
public $SurveyDataList;
After running, I am getting only an empty object in swagger ui like this {}.
I found the solution ,
in my controller I defined my gameData function like this,
/**
* #OA\Post(path="/gameData",
* tags={"user"},
* summary="Add Game Data of User",
* security={{"bearerAuth":{}}}, *
* description="",
* operationId="gameData",
* #OA\RequestBody(
* required=true,
* description="Created user object",
* #OA\JsonContent(
* ref="#/components/schemas/Game"
* )
* ),
* #OA\Response(response="default", description="successful operation")
* )
*/
public function gameData()
{
}
And in model.. I defined 3 properties where two of them are of type numbers and thirs one as array with Items in it.
/**
* #OA\Property(
* property="CurrentPuzzle",
* type="number",
* enum="1",
* description="Store current puzzle"
* )
*/
/**
* #OA\Property(
* property="OpenedLevel",
* type="number",
* enum="1",
* description="Store current level"
* )
*/
/**
* #OA\Property(
* property="RewardPuzzlePiecess",
* type="array",
* * #OA\Items(
* type="number",
* description="The survey ID",
* #OA\Schema(type="number")
* ),
* description="Store reward index"
* )
*/
The problem is that I need the documentation to show that it is possible to transfer the field colums in the form of an array and in it the following fields (name, description, created_at, updated_at, author). json is successfully generated but in the swagger-editor documentation it is not visible these fields
/**
* #SWG\Get(path="/articles",
* tags={"Article"},
* summary="Get all Articles",
* description="Show list of Articles",
* operationId="all",
* produces={"application/json"},
* #SWG\Parameter(
* name="columns",
* in="query",
* description="get specific columns",
* required=false,
* type="array",
* collectionFormat="multi",
* #SWG\Items(
* type="string",
* #SWG\Property(property="name", type="string"),
* #SWG\Property(property="description", type="string"),
* #SWG\Property(property="author", type="string"),
* #SWG\Property(property="created_at", type="string"),
* #SWG\Property(property="updated_at)", type="string")
* )
* ),
* #SWG\Response(response="200"),
* #SWG\Response(response=500)
* ),
* )
*/