PHP uses Swagger to generate good-looking API documents

It is not impossible to generate good-looking API documents using Swagger, but it is very simple.

First of all, I use the Laravel framework, so I install swagger-php on Laravel.

1. Install swagger-php

composer require zircote/swagger-php

swagger-php provides command line tools, so you can install them globally and add the path of the tool to PATH.

composer global require zircote/swagger-php

Then add the zircote/swagger-php/bin directory to the PATH. I can't use this thing, so I won't study it.

2. Set up an interface for outputting API document data

a) Generate a controller: SwaggerController

b) Add a method: getJSON()

    public function getJSON()
    {
        $swagger = \OpenApi\Generator::scan([app_path('Http/Controllers/')]);
        return response()->json($swagger, 200);
    }

Some articles write \Swagger\scan(), but I reported an error here and said that this class cannot be found. After checking the official documentation, you need to use \OpenApi\Generator::scan(). It may be that the new version has been modified.

c) Set up routing

Or, the path is different. My choice. Therefore, the access path must be prefixed: /api.

Route::group(['prefix' => 'swagger'], function () {
    Route::get('json', [\App\Http\Controllers\SwaggerController::class, 'getJSON']);
});

d) Test access

access http://localhost:8000/api/swagger/jsonIf you see that the page outputs json normally, it means that the configuration is successful. Otherwise, follow the error prompt to modify it one by one.

III. Use

GET method

    /**
      * @OA\Get(
      * tags={"Data Management"},
      * summary="data query",
      * path="/api/data/search",
      * @OA\Response(response="200", description="Display a listing of projects."),
      * @OA\Parameter(
      * description="data name",
      * in="query",
      * name="name",
      * required=false,
      * @OA\Schema(type="string"),
      * ),
      * @OA\Parameter(
      * description="status",
      * in="query",
      * name="status",
      * required=false,
      * @OA\Schema(type="integer"),
      * ),
      * @OA\Parameter(
      * description="Number of records per page",
      * in="query",
      * name="page-size",
      * required=false,
      * @OA\Schema(type="integer"),
      * ),
      * @OA\Parameter(
      * description="Current page number",
      * in="query",
      * name="current-page",
      * required=false,
      * @OA\Schema(type="integer"),
      * ),
      * )
      */

Here:

in indicates where the parameter appears. If you query, use & is spelled behind the url; path is similar to /api/data/search/{param}; header is included in the request header; cookies are naturally placed in the cookie.

In this version, formData and body are gone.

required You can know that true is a required item and false is an optional item.

POST method

    /**
      * @OA\Post(
      * tags={"Data Management"},
      * summary="Add data",
      * path="/api/data",
      * @OA\Response(response="200", description="Display a listing of projects."),
      * @OA\RequestBody(
      * @OA\MediaType(
      * mediaType="x-www-form-urlencoded",
      * @OA\Schema(
      * ref="#/components/schemas/DataModel",
      * ),
      * ),
      * ),
      * )
      */

Because my front-end code post is submitted in form, the post method here must use @OA\RequestBody.

@OA\Parameter is a parameter and can be placed on the url, but the data does not appear on the url when the post form is submitted.

@OA\MediaType This: x-www-form-urlencoded form submission; application/json submits json format data; multipart/form-data file upload;

     *             @OA\Schema(
     *                 ref="#/components/schemas/DataModel",
     *             ),

This is associated with a defined schema, so that it is not possible to write it in each interface comment using the same data.

You can also write it separately here:

 * @OA\Schema(
 *   required={"name", "code"},
 *   @OA\Property(property="name", type="string", title="Name", description="This is the name"),
 *   @OA\Property(property="code", type="string", title="Code", description="This is the code"),
 *   @OA\Property(property="phone", type="string", title="Telephone", description="This is the phone number"),
 * ),

As above, write as many parameters as @OA\Property.

The required here is an array, and all the required items are required.

The other methods are similar, and you will record it if you use it later.

4. Show swagger ui

Download the code for swagger ui:/swagger-api/swagger-ui/releases

After decompression, copy the dist directory in the directory to the public directory of laravel and rename it to swagger-ui. Just take the file name casually, just don't conflict.

Find the contents in this swagger-ui directory:

 = function() {
  //<editor-fold desc="Changeable Configuration Block">
  // the following lines will be replaced by docker/configurator, when it runs in a docker-container
   = SwaggerUIBundle({
    url: "/api/swagger/json",
    dom_id: '#swagger-ui',
    deepLinking: true,
    presets: [
      ,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      
    ],
    layout: "StandaloneLayout"
  });
  //</editor-fold>
};

Mainly change the url item. Change to the route address set earlier. Here is "/api/swagger/json".

Access after completionhttp://localhost:8000/swagger-ui/You can see the API document formed by swagger.

This is the end of this article about using Swagger to generate good-looking API documents for PHP. For more related PHP Swagger content, please search for my previous articles or continue browsing the related articles below. I hope everyone will support me in the future!