Using ThinkPHP6 to automatically generate API documents

As APIs become more and more widely used, automatically generating API documents has become an indispensable tool. This article will introduce how to use the ThinkPHP6 framework to automatically generate API documents.

1. Introduction to ThinkPHP6 framework

ThinkPHP6 is an efficient, simple, convenient and flexible open source framework developed using PHP language. It adopts an object-oriented development model, supports MVC (Model-View-Controller) architecture, and has powerful functions such as routing, caching, verification, and template engines.

2. Install Swagger UI

Swagger is an automatic generation tool for API documents. It can automatically generate API documents and provide a Web interface to demonstrate the execution results of the API. When using ThinkPHP6 to automatically generate API documents, we need to install Swagger first.

We can install Swagger through the Composer tool. Enter in the command line:

composer require zircote/swagger-php

After the installation is complete, create a Swagger configuration file in the root directory of the project and name it swagger.php:

<?php
return [
    'swagger' => [
        'api' => [
            'title' => 'API文档',  //API文档的标题
        ],
        'paths' => [
            APP_PATH . '/',
        ],
        'exclude' => [
        ],
        'swagger-ui' => [
            'title' => 'API文档',  //API文档的标题
        ],
        'securityDefinitions' => [
        ],
    ],
];

3. Define API document comments

In order for Swagger to automatically identify and generate API documents, we need to add corresponding comments to the code. ThinkPHP6 provides a custom comment format for defining API documentation.

Define API document comments in the controller:

<?php
declare(strict_types=1);

namespace appcontroller;

class Example
{
    /**
     * @OAGet(
     *      path="/example/index",
     *      operationId="exampleIndex",
     *      tags={"Example"},
     *      summary="示例接口",
     *      description="这是一个示例接口",
     *      @OAResponse(
     *          response=200,
     *          description="操作成功",
     *      ),
     *      @OAResponse(
     *          response=401,
     *          description="未授权",
     *      ),
     *      security={
     *          {"Bearer": {}}
     *      }
     * )
     */
    public function index()
    {
        //接口代码
    }
}

In the above code, the comment tag starting with @OA is parsed into Swagger's canonical format. Among them, @OAGet defines the request method of the API as the Get method; path defines the path of the API; operationId defines the id of the operation; tags defines the tag to which the API belongs; summary defines the overview of the API; description defines the detailed description of the API. ; @OAResponse defines the response result and status code of the API; security defines the access permissions of the API.

4. Generate API documentation

After defining the API documentation annotations, we can use Swagger to generate API documentation. Enter the following command on the command line:

php think swagger:export --output public/swagger.json

This command will save the API document to the swagger.json file in the public directory.

5. Access API documentation

Use Swagger UI to display API documentation. We can deploy the Swagger UI project to a web server or run it locally.

When running locally, we can use the following command to quickly start a Swagger UI service:

docker run --rm -p 8080:8080 -e SWAGGER_JSON=/data/swagger.json -v /path/to/swagger.json:/data/swagger.json swaggerapi/swagger-ui

Among them, /path/to/swagger.json is the absolute path of the swagger.json file.

Visit http://localhost:8080 in the browser to view the API documentation.

6. Summary

This article introduces how to use the ThinkPHP6 framework and Swagger to automatically generate API documents. Automatically generating API documents can improve development efficiency and reduce maintenance costs. Through the introduction of this article, I believe that readers can already skillfully use the ThinkPHP6 framework and Swagger to achieve automatic generation of API documents.

The above is the detailed content of Using ThinkPHP6 to automatically generate API documents. For more information, please follow other related articles on the PHP Chinese website!