Related
I am using "darkaonline/l5-swagger" version 8.0 laravel(v 8.12) package for api documentation. My PHP version is 8.0.2. I created api annotation for GET and POST request. The post request automatically send "Origin" header. The Get method is not sending "Origin" header by default.
Package link: https://github.com/DarkaOnLine/L5-Swagger
I need two things for this:
I want to change the default value of "Origin" header of POST request
I want to add custom "Origin" header in GET request
Below is my sample POST request
/**
* #OA\Post(
* path="/auth/login",
* summary="Login",
* description="This api will be used for login of all roles",
* operationId="authLogin",
* tags={"auth"},
* #OA\Parameter(
* name="Origin",
* in="header",
* description="Origin",
* required=true,
* example="http://example.com",
* schema={
* "type"="string"
* },
* style="simple",
* ),
* #OA\RequestBody(
* required=true,
* description="Pass user credentials",
* #OA\JsonContent(
* required={"email","password"},
* #OA\Property(property="email", type="string", format="email", example="user1#mail.com"),
* #OA\Property(property="password", type="string", format="password", example="PassWord12345"),
* ),
* ),
* #OA\Response(
* response=422,
* description="Wrong credentials response",
* #OA\JsonContent(
* #OA\Property(property="error",
* type="object",
* #OA\Property(property="message",
* type="string",
* example="Email required"
* ),
* #OA\Property(property="field",
* type="string",
* example="email"
* )
* ),
* ),
* ),
* #OA\Response(
* response=200,
* description="Login success",
* #OA\JsonContent(
* #OA\Property(property="data",
* type="object",
* #OA\Property(property="status", type="boolean", example=true),
* ),
* ),
* )
* )
*/
Below is my sample GET request
/**
* #OA\Get(
* path="/school-courses",
* summary="Get school courses",
* description="This api will be used to get all course of school",
* operationId="getSchoolCourse",
* tags={"frontend"},
* #OA\Parameter(
* name="Origin",
* in="header",
* description="Origin",
* required=true,
* example="http://example.com",
* schema={
* "type"="string"
* },
* style="simple",
* ),
* #OA\Response(
* response=200,
* description="Success",
* #OA\JsonContent(
* #OA\Items(
* #OA\Property(property="id", type="integer", example=1),
* #OA\Property(property="price", type="integer", example=29),
* #OA\Property(property="teacher_id", type="integer", example=null),
* #OA\Property(property="category_id", type="integer", example=null),
* #OA\Property(property="program_id", type="integer", example=null),
* #OA\Property(property="locale_id", type="integer", example=7),
* #OA\Property(property="status_id", type="integer", example=null),
* #OA\Property(property="level", type="integer", example=null),
* #OA\Property(property="created_by", type="integer", example=null),
* #OA\Property(property="lessons", type="integer", example=10),
* #OA\Property(property="created_at", type="string", example="2021-03-31T23:20:09.000000Z"),
* #OA\Property(property="updated_at", type="string", example="2021-03-31T23:20:09.000000Z"),
* #OA\Property(property="currency", type="object",
* #OA\Property(property="id", type="integer", example=1),
* #OA\Property(property="symbol", type="string", example="KZT"),
* #OA\Property(property="name", type="string", example="Kazakhstani Tenge"),
* #OA\Property(property="symbol_native", type="string", example="тңг."),
* #OA\Property(property="decimal_digits", type="integer", example=2),
* #OA\Property(property="rounding", type="integer", example=0),
* #OA\Property(property="code", type="string", example="KZT"),
* #OA\Property(property="name_plural", type="string", example="Kazakhstani Tenge"),
* #OA\Property(property="created_at", type="string", example="2021-03-31T23:20:09.000000Z"),
* #OA\Property(property="updated_at", type="string", example="2021-03-31T23:20:09.000000Z"),
* ),
* #OA\Property(property="course_locale", type="object",
* #OA\Property(property="id", type="integer", example=1),
* #OA\Property(property="locale_id", type="integer", example=1),
* #OA\Property(property="name", type="string", example="new nm 2"),
* #OA\Property(property="image", type="string", example="dummy.png"),
* #OA\Property(property="description", type="string", example="course description"),
* #OA\Property(property="image_url", type="string", example="http://127.0.0.1:8000/storage/dummy.png"),
* #OA\Property(property="created_at", type="string", example="2021-03-31T23:20:09.000000Z"),
* #OA\Property(property="updated_at", type="string", example="2021-03-31T23:20:09.000000Z"),
* ),
* #OA\Property(property="author", type="object",
* #OA\Property(property="id", type="integer", example=1),
* #OA\Property(property="name", type="string", example="user 2"),
* #OA\Property(property="email", type="string", example="user#example.com"),
* #OA\Property(property="description", type="string", example="course description"),
* #OA\Property(property="profile_image", type="string", example="http://127.0.0.1:8000/storage/dummy.png"),
* #OA\Property(property="created_at", type="string", example="2021-03-31T23:20:09.000000Z"),
* #OA\Property(property="facebook_url", type="string", example="http://facebook.com"),
* #OA\Property(property="twitter_url", type="string", example="http://twitter.com"),
* #OA\Property(property="instagram_url", type="string", example="http://instagram.com"),
* #OA\Property(property="status", type="string", example="Active"),
* ),
* ),
* ),
* ),
* )
*/
Below is my default controller annotation
/**
* #OA\Info(title="API Documentation", version="1.0")
* #OA\Schemes(format="http")
* #OA\SecurityScheme(
* securityScheme="bearerAuth",
* in="header",
* name="bearerAuth",
* type="http",
* scheme="bearer",
* bearerFormat="JWT",
* )
*/
I also noticed that when we add "Origin", it is showing in the CURL preview but its not adding in api request header.
Can someone please guide me on what i'm missing here?
Thanks in advance.
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\MediaType(
* mediaType="multipart/form-data",
* #OA\Schema(
* #OA\Property(
* property="resume",
* type="file",
* format="file"
* ),
* )
* )
* ),
* )
* )
* ),
* )
*/
#OA\RequestBody(
#OA\MediaType(
mediaType="multipart/form-data",
#OA\Schema(
allOf={
#OA\Schema(ref="#components/schemas/item"),
#OA\Schema(
#OA\Property(
description="Item image",
property="item_image",
type="string", format="binary"
)
)
}
)
)
),
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"
* )
*/
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.