How to generate API documentation using Swagger in PHP

With the continuous development of web applications, API has become one of the standards for modern web application development. However, as the number and complexity of APIs increases, maintaining and documenting them becomes increasingly complex. To solve this problem, Swagger came into being. It is a tool for generating API documentation, making it easier for developers to maintain and document APIs, while also providing visual documentation and various other features. In this article, we will discuss how to generate API documentation using Swagger in PHP.

First, we need to install Swagger. There are many versions and implementations of Swagger, but we will use Swagger-php here, which is an open source PHP library that makes it easy to integrate Swagger into PHP code. We can install Swagger-php in our project using Composer:

composer require zircote/swagger-php

Once we have Swagger-php installed, we can start writing the Swagger specification for our API. A Swagger specification is a JSON or YAML file that describes all the details of an API, including endpoint URLs, request and response parameters, data model, and error codes. In Swagger-php, we can use PHP annotations to write specifications. Let’s look at a simple example:

/**
 * @OAInfo(title="我的API", version="1.0")
 */

/**
 * @OAGet(
 *     path="/users",
 *     summary="获取所有用户",
 *     @OAResponse(response="200", description="成功响应")
 * )
 */

/**
 * @OAGet(
 *     path="/users/{id}",
 *     summary="获取用户详情",
 *     @OAParameter(name="id", in="path", required=true, description="用户ID"),
 *     @OAResponse(response="200", description="成功响应"),
 *     @OAResponse(response="404", description="用户不存在")
 * )
 */

In this example, we have used @OA annotation to write the Swagger specification. @OA is a namespace in the Swagger-php library used to define different types of Swagger elements, such as Info, Get, Response and Parameter. We can use the @OAInfo annotation to describe the basic information of the API, such as title and version. In the @OAGet annotation, we define two endpoints: /users and /users/{id}. We describe the request parameters and responses, and specify success and error response codes. This is just a small example, but you can write more complex Swagger specifications by using other @OA annotations, and even describe the authentication and authorization of the API.

Once we have written our Swagger specification, we can use Swagger-php to convert it into a visual document. For this we can use Swagger-ui, an HTML, CSS and JavaScript library for rendering Swagger specifications. We can use the Swagger-ui-php package in PHP to integrate Swagger-ui. We can install Swagger-ui-php in our project using Composer:

composer require swagger-api/swagger-ui

Once we have Swagger-ui-php installed, we can integrate Swagger-ui into our PHP application. We can add the following line to our HTML code to load Swagger-ui:

<link rel="stylesheet" type="text/css" href="/vendor/swagger-api/swagger-ui/dist/swagger-ui.css">
<div id="swagger-ui"></div>
<script src="/vendor/swagger-api/swagger-ui/dist/swagger-ui-bundle.js"></script>
<script src="/vendor/swagger-api/swagger-ui/dist/swagger-ui-standalone-preset.js"></script>
<script>
  window.onload = function() {
    // 使用来自后端的Swagger JSON文件构造请求
    SwaggerUIBundle({
      url: "/api/swagger.json",
      dom_id: '#swagger-ui',
      presets: [
        SwaggerUIBundle.presets.apis,
        SwaggerUIStandalonePreset // 用于额外的UI依赖
      ],
      layout: "StandaloneLayout"
    })
  }
</script>

In this example, we load the CSS and JavaScript files of Swagger-ui and render them in a -ui" ID in the DIV element. We use JavaScript code to load the Swagger JSON file from the backend and use SwaggerUIBundle to convert it into a beautiful document.

Finally, in order for Swagger-ui to load our Swagger specification, we need to add a route to our application that returns the Swagger JSON file.

use OpenApiAnnotations as OA;

$app->get('/api/swagger.json', function() use ($app) {
  $openapi = OpenApiscan([__DIR__ . '/routes']);
  return $app->json(json_decode($openapi->toJson()));
});

// 或者用这种方式

/**
 * @OAServer(url="http://localhost:8000")
 */

/**
 * @OAInfo(title="我的API", version="1.0")
 */

/**
 * @OAGet(
 *     path="/users",
 *     summary="获取所有用户",
 *     @OAResponse(response="200", description="成功响应")
 * )
 */

/**
 * @OAGet(
 *     path="/users/{id}",
 *     summary="获取用户详情",
 *     @OAParameter(name="id", in="path", required=true, description="用户ID"),
 *     @OAResponse(response="200", description="成功响应"),
 *     @OAResponse(response="404", description="用户不存在")
 * )
 */
$app->get('/api/swagger.json', function() use ($app) {
  $openapi = OpenApiscan([__DIR__ . '/routes']);
  return $app->json(json_decode($openapi->toJson()));
});

In this example, we use OpenApi annotations to write the Swagger specification, which is different from the previous example. We also added a route to return the Swagger JSON file. We use the OpenApiscan PHP function to scan our routes folder and convert the API definition into a Swagger JSON object, which is then converted into a JSON string and returned to the client.

In this article, we learned how to generate API documentation in PHP using Swagger-php and Swagger-ui. As the number and complexity of our APIs increases, Swagger can help us maintain and document them more easily, while providing visual API documentation and various other features. By using PHP annotations to write Swagger specifications, we can avoid manually writing documentation and make our code clearer and easier to maintain.

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