How to use the Hyperf framework for API documentation generation

How to use the Hyperf framework to generate API documents

Introduction:
With the rapid development of the Internet, API (Application Programming Interface) has become indispensable It can connect different applications to realize data sharing and interaction. For development teams, good API documentation is an important tool to ensure team collaboration. This article will introduce how to use the Hyperf framework to generate clear and easy-to-use API documentation, and demonstrate it through specific code examples.

1. Preparation work
Before you start using the Hyperf framework to generate API documents, you need to make the following preparations:

1. Install the Hyperf framework: Use the Composer tool to install it easily and quickly Hyperf framework.
2. Configure routing: Configure routing information in the config/routes.php file.
3. Install the API documentation generation tool: The Hyperf framework has an officially recommended API documentation generation tool called Swaggervel, which can be installed through Composer.

2. Generate API documentation
The following are the specific steps and code examples for using the Hyperf framework to generate API documentation:

1. Install Swaggervel

   composer require overtrue/laravel-swagger

2. Create a document generator class
   Create a DocGenerator.php file under the app/Doc folder and write the following code in it:

   <?php
   
   namespace AppDoc;
   
   use HyperfValidationContractValidatorFactoryInterface;
   use OvertrueLaravelSwaggerRequest;
   use OvertrueLaravelSwaggerSwagger as BaseSwagger;
   
   class DocGenerator
   {
    protected $validator;
   
    public function __construct(ValidatorFactoryInterface $validator)
    {
        $this->validator = $validator;
    }
   
    public function generate()
    {
        $swagger = new BaseSwagger([
            'swagger' => '2.0',
            'info' => [
                'title' => config('app.name'),
                'version' => config('app.version'),
            ],
        ]);
   
        $routes = app('router')->getRoutes();
   
        foreach ($routes as $route) {
            $methods = $route->methods();
            $path = $route->uri();
   
            foreach ($methods as $method) {
                $request = new Request([
                    'method' => $method,
                    'uri' => $route->uri(),
                ]);
   
                $docBlock = $route->getAction()['doc'] ?? null; // 从Route中获取注释
   
                $parameters = [];
   
                $validator = $this->validator->make($request->all(), $docBlock ? $docBlock['rules'] : []);
   
                foreach ($validator->failed() as $field => $messages) {
                    $parameters[] = [
                        'name' => $field,
                        'in' => 'query',
                        'required' => true,
                        'description' => implode(', ', $messages),
                    ];
                }
   
                $responses = [];
   
                $responses[] = [
                    'statusCode' => 200,
                    'description' => '请求成功',
                    'data' => [
                        'type' => 'object',
                        'properties' => [
                            'code' => [
                                'type' => 'integer',
                            ],
                            'message' => [
                                'type' => 'string',
                            ],
                            'data' => [
                                'type' => 'object',
                                'nullable' => true,
                            ],
                        ],
                    ],
                ];
   
                $swagger->addPath($path, $method, [
                    'parameters' => $parameters,
                    'responses' => $responses,
                ]);
            }
        }
   
        return $swagger->toYaml();
    }
   }

3. Configure access routing
   Add the following routing configuration in the config/routes.php file:

   use AppDocDocGenerator;
   
   Router::get('/api/docs', function (DocGenerator $docGenerator) {
    return $docGenerator->generate();
   });

4. Generate API documentation
   Execute the following command in the terminal to generate API documentation:

   php bin/hyperf.php serve

The above is the detailed content of How to use the Hyperf framework for API documentation generation. For more information, please follow other related articles on the PHP Chinese website!