Rumah > Artikel > pembangunan bahagian belakang > Cara menggunakan dokumentasi API berasaskan OAS dalam PHP
Cara menggunakan dokumentasi API berasaskan OAS dalam PHP
- WBOYasal
- 2023-06-17 11:03:101090semak imbas
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: stringDalam 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>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!