cari

Rumah  >  Artikel  >  pembangunan bahagian belakang  >  Pembangunan PHP: Cara menggunakan Swagger untuk mengekalkan dokumentasi API

Pembangunan PHP: Cara menggunakan Swagger untuk mengekalkan dokumentasi API

WBOY
WBOYasal
2023-06-15 09:37:17972semak imbas

Dengan perkembangan pesat Internet, API Web telah menjadi teras menyokong aplikasi terbuka. Kebolehskalaan dan kebolehgunaan semula API menjadikannya alat penting untuk pertukaran data dan kerjasama antara sistem yang berbeza. Walau bagaimanapun, pembangun sering menghadapi soalan biasa: Bagaimana untuk mengekalkan dokumentasi API dan memastikan kebolehpercayaan API?

Swagger ialah rangka kerja sumber terbuka yang menyediakan penyelesaian lengkap untuk reka bentuk, dokumentasi, ujian dan penggunaan API. Artikel ini akan meneroka cara menggunakan Swagger untuk mengekalkan dokumentasi API untuk mengurus dan mengekalkan API sedia ada dengan lebih baik.

1. Konsep asas Swagger

Swagger mencipta dan mendokumenkan API melalui fail spesifikasi JSON atau YAML yang menerangkan API. Fail ini dipanggil spesifikasi Swagger.

Fail spesifikasi swagger mengandungi konsep berikut:

  1. Laluan: Laluan API ialah pengecam untuk sumber. Contohnya, /users mewakili semua pengguna dan /users/{id} mewakili pengguna.
  2. Kaedah: Kaedah HTTP seperti GET, PUT, POST, DELETE dan HEAD.
  3. Parameter: Permintaan parameter (badan permintaan HTTP, laluan URL dan/atau parameter rentetan pertanyaan).
  4. Respons: Struktur respons HTTP, kod status dan jenis badan respons (badan respons HTTP).
  5. Model: Struktur Objek Pemindahan Data (DTO) dan Objek Tindak Balas. Teg
  6. : Kumpulan sumber API secara logik untuk bacaan mudah.

2. Penggunaan Swagger

  1. Pasang Swagger UI

Swagger UI ialah alat sumber terbuka yang membolehkan kami mencipta interaktif The Fail spesifikasi swagger dipaparkan dalam antara muka. Tujuan utamanya adalah untuk menyediakan dokumentasi yang jelas dan interaktif serta membolehkan kami menguji dan nyahpepijat API.

Gunakan arahan berikut untuk memasang UI Swagger: 

npm install swagger-ui-dist
  1. Tulis fail spesifikasi Swagger

Tulis fail spesifikasi Swagger untuk menerangkan laluan dan kaedah kami API , parameter, respons dan maklumat lain.

Berikut ialah contoh: 

swagger: '2.0'
info:
  title: User API Root
  version: 1.0.0
paths:
  /users:
    get:
      tags:
        - users
      description: Returns all users
      produces:
        - application/json
      responses:
        200:
          description: A list of user names
          schema:
            type: object
            properties:
              id:
                type: integer
                example: 123
              name:
                type: string
                example: John Doe

Dalam contoh ini, kami mentakrifkan laluan API "/users" dan kaedah GET yang mengembalikan JSON yang mengandungi "id" dan "nama" Array objek sebagai tindak balas.

  1. Sepadukan Swagger UI

Sepadukan Swagger UI dalam aplikasi web anda untuk memaparkan fail spesifikasi Swagger anda. Tambahkan kod HTML berikut pada halaman web anda: 

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Swagger UI</title>
  <link rel="stylesheet" type="text/css" href="./node_modules/swagger-ui-dist/swagger-ui.css">
</head>
<body>
  <div id="swagger-ui"></div>
  <script src="./node_modules/swagger-ui-dist/swagger-ui-bundle.js"></script>
  <script>
    window.onload = function() {
      SwaggerUIBundle({
        url: "https://api.example.com/swagger",
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIBundle.SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
      })
    }
  </script>
</body>
</html>

Dalam contoh ini, kami memuatkan UI Swagger dalam fail HTML dan menghantar alamat URL fail spesifikasi Swagger kepada SwaggerUIBundle untuk memaparkan dokumentasi API.

  1. Menguji dan menyahpepijat API

Uji dan nyahpepijat API dalam aplikasi web menggunakan Swagger UI.

Melalui Swagger UI, kita boleh:

  • Lihat dokumentasi antara muka.
  • Automasikan ujian dan semak hasil tindak balas API.
  • Nyahpepijat API sambil menjana coretan kod.

Ringkasan

Swagger ialah rangka kerja yang sangat baik yang boleh menyediakan pembangun penyelesaian lengkap untuk reka bentuk, dokumentasi, ujian dan penggunaan API. Menggunakan Swagger, kami boleh mengurus dan mengekalkan API sedia ada dengan lebih baik. Ini juga merupakan salah satu cara terbaik di bawah model pembangunan berpusat.

Atas ialah kandungan terperinci Pembangunan PHP: Cara menggunakan Swagger untuk mengekalkan dokumentasi API. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!

php json html 标识符 字符串 接口 delete 对象 http ui 自动化
Kenyataan：
Kandungan artikel ini disumbangkan secara sukarela oleh netizen, dan hak cipta adalah milik pengarang asal. Laman web ini tidak memikul tanggungjawab undang-undang yang sepadan. Jika anda menemui sebarang kandungan yang disyaki plagiarisme atau pelanggaran, sila hubungi admin@php.cn
Artikel sebelumnya：Cara menggunakan PHP dan Selenium untuk melengkapkan pembangunan dan amalan perangkak web automatikArtikel seterusnya：Cara menggunakan PHP dan Selenium untuk melengkapkan pembangunan dan amalan perangkak web automatik

Artikel berkaitan

Lihat lagi