How to use OAS based API documentation in PHP-PHP Tutorial-php.cn

How to use OAS based API documentation in PHP

WBOY

Release： 2023-06-17 11:14:01

Original

1121 people have browsed it

With the rapid development of the Internet, API (Application Programming Interface) has become an indispensable part. The function of API is to allow interaction and communication between different applications to achieve data sharing and business connectivity. With the increase and expansion of APIs, how to effectively manage and maintain API documents has become a problem that needs to be solved. In this regard, API documentation based on OAS (OpenAPI Specification) has become an effective management method. Next, we will introduce how to use OAS-based API documentation in PHP.

1. What is OAS

OAS is the abbreviation of OpenAPI Specification, which can also be called Swagger specification. OAS is a language for defining APIs. It is based on JSON or YAML format and is used to define the specifications of RESTful APIs to write and generate effective API documents and client code.

2. How to write OAS documents

You can use the Swagger editor to write OAS documents. At the same time, OAS also provides some specification requirements, such as the definition of API request, response, parameter and other formats. The following is a basic example of writing an API document based on OAS:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Example API
  description: "This is an example API for demonstration purposes."
paths:
  /example:
    get:
      summary: Example Endpoint
      description: "This endpoint returns an example response."
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  example_property:
                    type: string

Copy after login

In the OAS document, you need to define the basic information of the API, such as URL, request and response format, etc. The above is a simple example, which contains an endpoint named /example, which returns a response object in json format.

3. How to use OAS-based API documents

Before using OAS-based API documents, you need to know how to parse and verify OAS documents. There are currently many open source tools and libraries that can help you achieve this task, such as OpenAPI Generator, Swagger Codegen, Swagger UI, etc. Here, we will use Swagger UI to demonstrate how to use OAS-based API documentation.

Download Swagger UI and extract it into the public folder in your PHP project. You can download the latest version from Swagger UI’s GitHub page.
Copy your OAS document to the public directory where Swagger UI is located, and name it swagger.json.
Edit the index.html file and change the URL in it to the path of your swagger.json file.
To use Swagger UI in PHP, you just need to include the following code in your PHP file:

<!DOCTYPE html>
<html>
<head>
    <title>My API documentation</title>
</head>
<body>
    <div id="swagger-ui"></div>
    <script src="swagger-ui/swagger-ui-bundle.js"></script>
    <script src="swagger-ui/swagger-ui-standalone-preset.js"></script>
    <script>
        window.onload = function() {
          const ui = SwaggerUIBundle({
            url: "./swagger.json",
            dom_id: "#swagger-ui",
            presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
            layout: "StandaloneLayout"
          })
        }
    </script>
</body>
</html>

Copy after login

At this point, you can access your Swagger UI to understand and Test your API now. Swagger UI automatically generates API documentation based on your OAS documentation, and you can test API requests and responses in the UI.

4. Summary

In this article, we introduced how to use OAS-based API documentation in PHP. OAS-based API documentation is an effective API document management method that can help us better maintain and manage APIs. If you want to learn more about the writing and use of OAS documents, it is recommended that you refer to the OAS official documentation and use some open source tools to implement and test it.

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