Shulou(Shulou.com)05/31 Report--

Most people do not understand the knowledge of this article "how to use Laravel Swagger", so the editor summarizes the following content, detailed content, clear steps, and has a certain reference value. I hope you can gain something after reading this article. Let's take a look at this "how to use Laravel Swagger" article.

Is swagger too spicy chicken?

This tutorial is based on Laravel to generate swagger as an example, in fact, this thing is basically no different from the language or the framework, because they all use the common json, scan the "language" predefined by swagger through the program, store the generated structure in json, and show it through swagger ui (or develop by yourself).

For php developers, most students don't like swagger very much. Because this looks so troublesome to write, I resist this thing when I think of the code that is written in php every minute, and it takes 10 minutes to write swagger.

Students with Java developers know that a large part of them use swagger because java maintains data structures and swagger integrates more flexibly in java.

At this time, if java sees php saying that swagger is anti-human, it will be too troublesome, a product of ancient times. The java friends around me will be delighted that they don't use anything so easy to use, and say that php is the best language in the world.

Why do I use swagger?

Recently, I have been writing auto-generated code, in fact, many Laravel now automatically generate CURD. For example, like laravel-admin, a command generates CURD, but after it is generated, the data looks cold. For example, there are some fields that do not need to be displayed, some are select associated enumerations, some are hasMany, and the api scaffolding of overtrue is also good.

So swaager can also be written and generated automatically according to business requirements.

L5-Swagger installation: composer require "darkaonline/l5-swagger" use: php artisan vendor:publish-- provider "L5Swagger\ L5SwaggerServiceProvider" php artisan l5-swagger:generate

Fill in the following example and then visit

/ api/documentation

@ OA\ Info is required

Example / * * @ 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" *) *) * / get request

If you want to match the values in path, in path queries 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= {* "oauth3_security_example": {"write:projects", "read:projects"} * *, *) * / POST request / * @ OA\ Post (* path= "/ api/test/store", * operationId= "api/test/store" * tags= {"Test"}, * summary= "Test creation", * description= "Test submission creation", * @ 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": {} *}, *) * / File upload parameters * @ OA\ RequestBody (* @ OA\ MediaType (* mediaType= "multipart/form-data") * @ OA\ Schema (* type= "object", * @ OA\ Property (* property= "file", * type= "file", *) *) Input is enumeration * @ OA\ Parameter (* name= "status", * in= "query", * description= "status", * required=true, * explode=true, * @ OA\ Schema (* type= "array", * default= "available") * @ OA\ Items (* type= "string", * enum = {"available", "pending", "sold"}, *) Body submits * @ OA\ RequestBody (* @ OA\ MediaType (* mediaType= "application/json"), * @ OA\ Schema (* @ OA\ Property (* property= "id") in Json mode * type= "string" *), * @ OA\ Property (* property= "name", * type= "string" *), * example= {"id": 10 "name": "Jessica Smith"} *), using the structure Schema as the request parameter * @ OA\ RequestBody (* description= "order placed for purchasing th pet", * required=true, * @ OA\ JsonContent (ref= "# / components/schemas/UserModel") *) Use of Schema / * * @ OA\ Schema (* schema= "UserModel", * required= {"username", "age"}, * @ OA\ Property (* property= "username", * format= "string", * description= "user name", * example= "Xiao Liao", *) * @ OA\ Property (* property= "age", * format= "int", * description= "age", * example=1, * nullable=true, *) * / enumerate

An enumeration creates a separate Schema

/ * * @ OA\ Schema (* schema= "product_status", * type= "string", * description= "The status of a product", * enum= {"available", "discontinued"}, * default= "available" *) * /

Map to specific fields in the model

* @ OA\ Property (* property= "status", * ref= "# / components/schemas/product_status" *)

So that front-end developers can

Association model

Similar to enumerations, through a Property association model

* @ OA\ Property (* property= "user_detail", * ref= "# / components/schemas/UserModel2" *)

Associated models and enumerations that can automatically generate the parameters of the request and the structure returned

Returned as model structure * @ OA\ Response (* response=200, * description= "successful operation", * @ OA\ JsonContent (* type= "array", * @ OA\ Items (ref= "# / components/schemas/UserModel") * @ OA\ Items (ref= "# / components/schemas/UserModel2") *) *)

For example, the front-end sister said to you that day, brother, what does payment status 3 represent? you may quickly say that it is a so-and-so state, but if you ask you what state 11 is, people will be sculptured in sand.

Through the Schema of swagger, the front-end staff can find out the structure information of the back-end.

Multiple mergers Schema/** * @ 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, *), *) *} *) * / Verification provides outh3 and apikey Write / * * @ OA\ SecurityScheme (* type= "apiKey", * in= "query", * securityScheme= "api_key", * name= "api_key" *) * / in the global configuration (or in any directory)

Add to the interface

Security= {{"api_key": {}

At this point, swagger Ui will have something like a lock.

You can enter your own token and bring token when you request it.

Problems that may be encountered

If you can't access the online environment, it may be a problem with your nginx configuration, because laravel-swagger outputs js by echo through file_content_get (). According to your nginx configuration, if it is .js or css is a static file, so you can't get to index.php, let alone execute the file_content_get function. You can refer to nginx configuration:

Charset utf-8;client_max_body_size 128Mlocation position / {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 this for your own; try_files $uri = 404 } the above is about the content of this article on "how to use Laravel Swagger". I believe we all have a certain understanding. I hope the content shared by the editor will be helpful to you. If you want to know more about the relevant knowledge, please follow the industry information channel.

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.