Home > Article > PHP Framework > Learn more about the use of Laravel Swagger
This article brings you relevant knowledge about laravel, which mainly introduces issues related to the use of Swagger. Let’s take a look at generating swagger based on Laravel as an example. I hope it will be helpful to everyone. help.
[Related recommendations: laravel video tutorial]
This tutorial is based on Laravel generating swagger as an example. In fact, this thing is basically the same as a language or a framework, because they all use public json, and scan the "language" predetermined by swagger through the program. ”, the generated structure is stored in json and displayed through swagger ui (or developed by yourself).
For PHP developers, most students dislike swagger. Because this seems to be very troublesome to write. When I think about the code that can be written in PHP in minutes, it takes 10 minutes to write swagger, and I resist this thing in my heart.
Students who are involved in Java development know that most of them use swagger, because Java needs to maintain the data structure, and swagger is more flexible to integrate in Java.
At this time, if you see php in java saying that swagger is anti-human, it will be too troublesome. It is a product of ancient times. The Java friends around me will be secretly happy that they don’t use such useful things, and they also say that PHP is the best language in the world.
I have been writing automatic code generation recently. In fact, Laravel now automatically generates CURD. For example, like laravel-admin, a command generates CURD, but after generation, the data looks very cold. For example, some fields do not need to be displayed, some need to be selected for associated enumerations, some are hasMany, and the overtrue (super) api scaffolding is also very good
Therefore, swaager can also write automated generation according to business needs
https://github.com/DarkaOnLine/L5-Swagger
composer require "darkaonline/l5-swagger"
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider" php artisan l5-swagger:generate
Fill in the following example to generate and then access
/api/documentation
@OA\Info is required
/** * @OA\Info( * version="1.0.0", * title="L5 OpenApi", * description="L5 Swagger OpenApi description", * @OA\Contact( * email="darius@matulionis.lt" * ), * @OA\License( * name="Apache 2.0", * url="http://www.apache.org/licenses/LICENSE-2.0.html" * ) * ) */
If you want to match the value in path, then in path query in query
/**
* @OA\Get(
* path="/projects/{id}",
* operationId="getProjectById",
* tags={"Projects"},
* summary="Get project information",
* description="Returns project data",
* @OA\Parameter(
* name="id",
* description="Project id",
* required=true,
* in="path",
* @OA\Schema(
* type="integer"
* )
* ),
* @OA\Response(
* response=200,
* description="successful operation"
* ),
* @OA\Response(response=400, description="Bad request"),
* @OA\Response(response=404, description="Resource Not Found"),
* security={
* {
* "oauth2_security_example": {"write:projects", "read:projects"}
* }
* },
* )
*/
/**
* @OA\Post(
* path="/api/test/store",
* operationId="api/test/store",
* tags={"Test"},
* summary="Test创建",
* description="Test提交创建",
* @OA\Parameter(
* name="id",
* description="",
* required=false,
* in="query",
* ),
* @OA\Response(
* response=200,
* description="successful operation",
* @OA\JsonContent(
* ref="#/components/schemas/Test"
* )
* ),
* @OA\Response(response=400, description="Bad request"),
* @OA\Response(response=404, description="Resource Not Found"),
* security={
* {
* "api_key":{}
* }
* },
* )
*/
* @OA\RequestBody( * @OA\MediaType( * mediaType="multipart/form-data", * @OA\Schema( * type="object", * @OA\Property( * property="file", * type="file", * ), * ), * ) * ),
* @OA\Parameter(
* name="status",
* in="query",
* description="状态",
* required=true,
* explode=true,
* @OA\Schema(
* type="array",
* default="available",
* @OA\Items(
* type="string",
* enum = {"available", "pending", "sold"},
* )
* )
* ),
* @OA\RequestBody(
* @OA\MediaType(
* mediaType="application/json",
* @OA\Schema(
* @OA\Property(
* property="id",
* type="string"
* ),
* @OA\Property(
* property="name",
* type="string"
* ),
* example={"id": 10, "name": "Jessica Smith"}
* )
* )
* ),
* @OA\RequestBody( * description="order placed for purchasing th pet", * required=true, * @OA\JsonContent(ref="#/components/schemas/UserModel") * ),
/**
* @OA\Schema(
* schema="UserModel",
* required={"username", "age"},
* @OA\Property(
* property="username",
* format="string",
* description="用户名称",
* example="小廖",
* ),
* @OA\Property(
* property="age",
* format="int",
* description="年龄",
* example=1,
* nullable=true,
* )
* )
*/
An enumeration creates a Schema separately
/**
* @OA\Schema(
* schema="product_status",
* type="string",
* description="The status of a product",
* enum={"available", "discontinued"},
* default="available"
* )
*/
Mapped to the model Specific fields
* @OA\Property( * property="status", * ref="#/components/schemas/product_status" * ),
So that front-end developers can
It is similar to the enumeration, through a Property association model
* @OA\Property( * property="user_detail", * ref="#/components/schemas/UserModel2" * ),
Associate the model and the enumeration For example, the requested parameters and parameters can be automatically generated, and the returned structure 
* @OA\Response( * response=200, * description="successful operation", * @OA\JsonContent( * type="array", * @OA\Items(ref="#/components/schemas/UserModel"), * @OA\Items(ref="#/components/schemas/UserModel2") * ) * ),
Just like the day the front-end girl told you, brother, payment status What does 3 stand for? Maybe you can quickly tell it is a certain state, but if I ask you what state 11 is, people will be confused.
Through swagger's Schema, front-end personnel can understand the structural information of the back-end, such as:
Everyone, these can be programmed automatically and generated automatically, and the work efficiency is not required Too cool
/**
* @OA\Schema(
* schema="UserModel",
* allOf={
* @OA\Schema(ref="#/components/schemas/UserModel2"),
* @OA\Schema(
* type="object",
* description="Represents an authenticated user",
* required={
* "email",
* "role",
* },
* additionalProperties=false,
* @OA\Property(
* property="email",
* type="string",
* example="user@example.com",
* nullable=true,
* ),
* )
* }
* )
*/
/** * @OA\SecurityScheme( * type="apiKey", * in="query", * securityScheme="api_key", * name="api_key" * ) */
In Add
security={{"api_key": {}}},
to the interface. At this time, a lock-like thing will appear in the swagger Ui.
You can enter your own token, and the token will be brought when making a request.
It can be combined with Laravel's own token verification. You can refer to the previously written article Laravel guard Chrysanthemum Guardian
For more usage methods, you can view the official website examples: https:/ /github.com/zircote/swagger-php/tree/master/Examples/petstore-3.0
If the online environment cannot be accessed, It may be a problem with your nginx configuration, because laravel-swagger echoes the js output through file_content_get(). Judging from your nginx configuration, if it is a .js or css file, it is a static file, so index.php cannot be reached, and the file_content_get function cannot be executed. You can refer to nginx configuration:
charset utf-8;
client_max_body_size 128M;
location / {
try_files $uri $uri/ /index.php$is_args$args;
}
location ~ \.php$ {
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_pass php74:9000 这个换成你自己的;
try_files $uri =404;
}
[Related recommendations: laravel video tutorial]
The above is the detailed content of Learn more about the use of Laravel Swagger. For more information, please follow other related articles on the PHP Chinese website!