Laravel development: How to use Laravel Swagger to generate API documentation?

Laravel development: How to use Laravel Swagger to generate API documentation?

When developing web applications, working with API documentation is often a tedious but essential task. Use Swagger to automatically generate and visualize API documentation. In Laravel development, we can use the Laravel Swagger extension package to easily generate Swagger API documentation. This article will guide you on how to use Laravel Swagger with Laravel.

1. Install Laravel Swagger

Use Composer to install the Laravel Swagger extension package:

composer require darkaonline/l5-swagger

2. Configure Laravel Swagger

Laravel Swagger depends on Swagger UI, so we need to publish the resources of Swagger UI to Laravel's public directory. Use the following command to complete the publishing:

php artisan vendor:publish --provider "L5SwaggerL5SwaggerServiceProvider"

After executing the publishing command, it will be in public/ You can see the swagger-ui directory under the vendor directory. This directory contains all the resources of Swagger UI.

Next, add the following lines to Laravel’s configuration file config/app.php:

'providers' => [
    ...
    L5SwaggerL5SwaggerServiceProvider::class,
],

'aliases' => [
    ...
    'Swagger' => L5SwaggerFacadesL5Swagger::class,
],

3. Add Swagger comments

In order to tell Laravel Swagger that there is no inferred API format, we need to add Swagger annotations to the code. These annotations allow Laravel Swagger to automatically parse your API and generate corresponding documentation.

/**
 * @OAGet(
 *      path="/users",
 *      operationId="getUsersList",
 *      tags={"Users"},
 *      summary="Get list of registered users",
 *      description="Returns list of users",
 *      @OAResponse(response="200", description="successful operation"),
 *      @OAResponse(response=401, description="Unauthorized"),
 *      @OAResponse(response=403, description="Forbidden"),
 *      @OAResponse(response=404, description="Not Found"),
 *      @OAResponse(response=500, description="Internal Server Error")
 *     )
 */

In the above example, we use the @OAGet annotation to indicate that this is a GET request. path The annotation defines the path to the API. The tags and summary comments are used to display summaries and tags in Swagger documents. Finally, the @OAResponse annotation exemplifies possible response states.

4. View Swagger documentation in Laravel

After completing all the previous steps, we can use the following URL to view the Laravel Swagger documentation:

http://your-app.dev/api/documentation

(Please note that if you are using Laravel 5.4 or above, you do not need to define .dev, please use .test or other local domain name instead)

Start Laravel's development server and access the URL above. You should be able to see the automatically generated Swagger documentation in your browser.

In the Swagger documentation, you can view the defined API, test the API based on Swagger annotations added to the API, and view possible response states.

Summary

In this article, we learned how to easily generate Swagger API documentation using the Laravel Swagger extension package. First, we installed Laravel Swagger, then started Swagger and added Swagger annotations to the API. Finally, we looked at the documentation generated by Laravel Swagger.

Using Laravel Swagger can greatly reduce the burden of manually writing API documentation and avoid possible errors and inconsistencies. By using Swagger UI, we can more easily view and test the API, while providing a developer-friendly interface.

The above is the detailed content of Laravel development: How to use Laravel Swagger to generate API documentation?. For more information, please follow other related articles on the PHP Chinese website!