How to use PHP and Swagger for API documentation generation-PHP Tutorial-php.cn

How to use PHP and Swagger for API documentation generation

王林

Release： 2023-05-11 17:52:02

Original

1764 people have browsed it

With the rapid development of the Internet, API (Application Programming Interface) has become a standard way of modern application development. API refers to a set of interfaces that allow applications to exchange data and functions, allowing applications to interact with each other conveniently and quickly.

After we create an API, in order to facilitate other developers to use our API, we need to write detailed documentation for the API. However, manually writing API documentation is a time-consuming and energy-consuming task, so using automated tools for API documentation generation is very necessary and effective.

This article will introduce how to use PHP and Swagger to generate API documents.

1. What is Swagger?

Swagger is a specification for describing and defining RESTful APIs. It can be used to generate human-readable documentation, as well as a code generator to generate client-side and server-side code. Swagger can also be used for API testing and debugging.

2. Swagger installation and configuration

To use Swagger to generate API documents, you first need to install it. We can use Composer to install Swagger. Composer is a dependency manager for PHP and can download the latest version of Swagger.

Use the following command to install Swagger:

composer require "swagger-api/swagger-ui:^3.50"

Copy after login

After the installation is complete, we need to perform some configurations for Swagger. Create a swagger.php file in the project root directory and add the following code:

<?php

require_once(__DIR__ . '/vendor/autoload.php');

use OpenApiAnnotations as OA;

$swagger = OpenApiscan('/path/to/your/controllers');

header('Content-Type: application/json');
echo $swagger;

Copy after login

In the above code, /path/to/your/controllers should be replaced with your own controller path. In addition, we also need to add some configurations to the composer.json file:

    "config": {
        "platform": {
            "php": "7.4"
        }
    },
    "autoload": {
        "classmap": [
            "app/",
            "database/",
            "routes/",
            "tests/"
        ]
    },
    "require": {
        "php": "^7.4",
        "laravel/framework": "^8.40",
        "tymon/jwt-auth": "^1.0",
        "doctrine/dbal": "^2.13",
        "swagger-api/swagger-ui": "^3.50"
    },
    "require-dev": {
        "facade/ignition": "^2.5",
        "fzaninotto/faker": "^1.9.1",
        "mockery/mockery": "^1.4.2",
        "nunomaduro/collision": "^6.0",
        "phpunit/phpunit": "^9.3.3"
    },

Copy after login

3. Use Swagger to generate API documents

After installing and configuring Swagger, we can start using it to generate API documentation. We can use the following command to generate API documentation:

php swagger.php > swagger.json

Copy after login

In the above command, swagger.php is the Swagger configuration file just created, and swagger.json is the API documentation file we generated.

4. Use Swagger UI to display API documents

After generating the API document, we hope to display it so that others can view it. You can use Swagger UI to display API documentation. Swagger UI is a JavaScript library used to display RESTful API information and its implementation described by Swagger.

We can add the following content to the index.php file in the public directory:

require_once(__DIR__ . '/../vendor/autoload.php');

$swagger = file_get_contents(__DIR__ . '/../swagger.json');
$swaggerData = json_decode($swagger, true);
?>
  <!DOCTYPE html>
  <html>
  <head>
    <meta charset="UTF-8">
    <title>Swagger UI</title>
    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui.min.css" >
    <style>
      html
      {
        box-sizing: border-box;
        overflow: -moz-scrollbars-vertical;
        overflow-y: scroll;
      }
      *, *:before, *:after
      {
        box-sizing: inherit;
      }

      body
      {
        margin:0;
        background: #fafafa;
      }
    </style>
  </head>

  <body>
  <div id="swagger-ui"></div>

  <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui-bundle.js"> </script>
  <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui-standalone-preset.js"> </script>
  <script>
      window.onload = function() {
          // Begin Swagger UI call region
          const ui = SwaggerUIBundle({
            url: "<?php echo '/swagger.json'; ?>",
            dom_id: '#swagger-ui',
            deepLinking: true,
            presets: [
              SwaggerUIBundle.presets.apis,
              SwaggerUIStandalonePreset
            ],
            plugins: [
              SwaggerUIBundle.plugins.DownloadUrl
            ],
            layout: "StandaloneLayout"
          })
          // End Swagger UI call region
          
          window.ui = ui
      }
  </script>
  </body>

  </html>

Copy after login

In the above code, we use the JavaScript library of Swagger UI, through which the generated The API documentation is presented in the form of beautiful HTML pages.

A sample page showing API documentation is shown below:

How to use PHP and Swagger for API documentation generation

##5. Conclusion

Using Swagger can easily document APIs Generate and manage. This article introduces how to use PHP and Swagger to generate API documents. The steps include installing and configuring Swagger, using Swagger to generate API documents, and using Swagger UI to display API documents. I believe that readers can easily use Swagger to generate their own API documents after the introduction in this article.

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