Cara menggunakan dokumentasi API berasaskan OAS dalam PHP-tutorial php-php.cn

Cara menggunakan dokumentasi API berasaskan OAS dalam PHP

WBOY

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

asal

1178 orang telah melayarinya

Dengan perkembangan pesat Internet, API (Antaramuka Pengaturcaraan Aplikasi) telah menjadi bahagian yang amat diperlukan. Fungsi API adalah untuk membenarkan interaksi dan komunikasi antara aplikasi yang berbeza untuk mencapai perkongsian data dan ketersambungan perniagaan. Dengan peningkatan dan pengembangan API, cara mengurus dan menyelenggara dokumen API dengan berkesan telah menjadi masalah yang perlu diselesaikan. Dalam hal ini, dokumentasi API berdasarkan OAS (Spesifikasi OpenAPI) telah menjadi kaedah pengurusan yang berkesan. Seterusnya, kami akan memperkenalkan cara menggunakan dokumentasi API berasaskan OAS dalam PHP.

1. Apakah itu OAS

OAS ialah singkatan dari Spesifikasi OpenAPI, yang juga boleh dipanggil spesifikasi Swagger. OAS ialah bahasa untuk mentakrifkan API Ia berdasarkan format JSON atau YAML dan digunakan untuk mentakrifkan spesifikasi API RESTful untuk menulis dan menjana dokumen API dan kod klien.

2. Cara menulis dokumen OAS

Anda boleh menggunakan editor Swagger untuk menulis dokumen OAS Pada masa yang sama, OAS juga menyediakan beberapa keperluan spesifikasi, seperti definisi permintaan API. respons, parameter dan format lain. Berikut ialah contoh asas menulis dokumen API berdasarkan 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

Salin selepas log masuk

Dalam dokumen OAS, anda perlu menentukan maklumat asas API, seperti URL, format permintaan dan respons, dsb. Di atas ialah contoh mudah, yang mengandungi titik akhir bernama /example, yang mengembalikan objek respons dalam format json.

3. Cara menggunakan dokumen API berasaskan OAS

Sebelum menggunakan dokumen API berasaskan OAS, anda perlu mengetahui cara menghuraikan dan mengesahkan dokumen OAS. Pada masa ini terdapat banyak alatan dan perpustakaan sumber terbuka yang boleh membantu anda mencapai tugas ini, seperti OpenAPI Generator, Swagger Codegen, Swagger UI, dsb. Di sini, kami akan menggunakan UI Swagger untuk menunjukkan cara menggunakan dokumentasi API berasaskan OAS.

Muat turun Swagger UI dan ekstraknya ke dalam folder awam dalam projek PHP anda. Anda boleh memuat turun versi terkini daripada halaman GitHub Swagger UI.
Salin dokumen OAS anda ke direktori awam tempat UI Swagger terletak dan namakannya swagger.json.
Edit fail index.html dan tukar URL di dalamnya kepada laluan fail swagger.json anda.
Untuk menggunakan Swagger UI dalam PHP, anda hanya perlu memasukkan kod berikut dalam fail PHP anda:

<!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>

Salin selepas log masuk

Pada ketika ini, anda boleh mengakses Swagger UI anda untuk memahami dan Menguji API anda sekarang. Swagger UI menjana dokumentasi API secara automatik berdasarkan dokumentasi OAS anda dan anda boleh menguji permintaan dan respons API dalam UI.

4. Ringkasan

Dalam artikel ini, kami memperkenalkan cara menggunakan dokumentasi API berasaskan OAS dalam PHP. Dokumentasi API berasaskan OAS ialah kaedah pengurusan dokumen API yang berkesan yang boleh membantu kami mengekalkan dan mengurus API dengan lebih baik. Jika anda ingin mengetahui lebih lanjut tentang penulisan dan penggunaan dokumen OAS, adalah disyorkan agar anda merujuk kepada dokumentasi OAS rasmi dan menggunakan beberapa alatan sumber terbuka untuk melaksanakan dan mengujinya.

Atas ialah kandungan terperinci Cara menggunakan dokumentasi API berasaskan OAS dalam PHP. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!