Home > Article > Backend Development > How to use PHP and Swagger for API documentation generation
How to use PHP and Swagger for API documentation generation
- 王林Original
- 2023-05-11 16:40:421759browse
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"
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;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"
},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
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>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:
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!