Menggunakan SwaggerUI untuk melaksanakan dokumentasi dalam talian API di Golang

Menggunakan SwaggerUI untuk melaksanakan dokumentasi dalam talian API di Golang

Dengan kemunculan seni bina aplikasi moden, API (Antara Muka Pengaturcaraan Aplikasi) telah menjadi komponen asas aplikasi web moden. Memandangkan bilangan API terus meningkat, menulis dan menyelenggara dokumentasi API telah menjadi tugas yang membosankan. Oleh itu, adalah sangat perlu untuk memudahkan proses penulisan dan penyelenggaraan dokumentasi API. Swagger ialah penyelesaian popular yang menyediakan alat dokumentasi yang berkuasa untuk API Web. Artikel ini akan memperkenalkan cara menggunakan SwaggerUI untuk melaksanakan dokumentasi dalam talian API di Golang.

Pengenalan kepada Swagger

Swagger ialah satu set alat binaan API sumber terbuka yang boleh membantu pembangun mereka bentuk, membina, mendokumenkan dan menguji API RESTful. Ia termasuk berbilang alatan seperti Editor Swagger, UI Swagger dan Codegen Swagger.

Antaranya, Swagger Editor ialah editor berasaskan pelayar web yang boleh membantu pembangun menulis dan mengedit spesifikasi Swagger ialah alat yang boleh menjadikan spesifikasi Swagger ke dalam dokumen API secara automatik dan kod API sebelah pelayan.

Menggunakan SwaggerUI untuk melaksanakan dokumentasi dalam talian API di Golang

Golang ialah bahasa pengaturcaraan yang sangat popular Kelebihannya ialah prestasi serentak yang tinggi dan overhed yang rendah. Ia menggunakan benang ringan yang dipanggil Goroutines untuk mengendalikan konkurensi dan menyokong kitar semula memori automatik dan pengumpulan sampah. Di Golang, anda boleh menggunakan perpustakaan go-swagger untuk melaksanakan dokumentasi dalam talian API.

1. Pasang Swagger

Pertama, anda perlu memasang Swagger, yang boleh dipasang melalui arahan berikut:

$ brew tap go-swagger/go-swagger
$ brew install go-swagger

2. Memulakan Golang projek

Seterusnya, anda perlu memulakan projek Golang pada komputer tempatan anda. Mencipta projek Golang bernama Go-Swagger-API pada mesin tempatan anda menggunakan arahan berikut:

$ mkdir Go-Swagger-API 
$ cd Go-Swagger-API 
$ go mod init Go-Swagger-API 

3. Cipta Definisi API

Untuk mencipta definisi API, anda perlu Buat fail YAML dan tentukan tetapan API di dalamnya. Dalam contoh ini, anda boleh mencipta fail bernama pets.yaml dan menambah kod berikut di dalamnya:

swagger: "2.0"
info:
  version: 1.0.0
  title: Petstore API 
produces:
- application/json
paths:
  /pets:
    get:
      summary: List all pets 
      responses:
        200:
          description: OK
        500:
          description: Internal Server Error
    post:
      summary: Add a new pet 
      parameters:
        - in: body
          name: body
          schema:
            "$ref": "#/definitions/pet"
          required: true
      responses:
        201:
          description: Created
        500:
          description: Internal Server Error

definitions:
  pet:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
      tag:
        type: string

4. Jana rangka kerja pelayan API

Seterusnya, anda perlu menggunakan alat go-swagger untuk menjana kod Penjana kod akan menjana kod secara automatik menggunakan konfigurasi yang ditakrifkan dalam langkah sebelumnya. Masukkan arahan berikut dalam terminal:

$ swagger generate server -A Go-Swagger-API -f pets.yaml

Arahan ini akan menjana rangka kerja bahagian pelayan berdasarkan definisi dalam fail YAML.

5. Mulakan pelayan API

Seterusnya, anda perlu memulakan pelayan API dan mengesahkan bahawa ia berfungsi dengan betul. Masukkan arahan berikut dalam terminal:

$ cd cmd/go-swagger-api-server/
$ go run main.go

Output sepatutnya kelihatan seperti berikut:

Serving Go-Swagger-API at http://127.0.0.1:8080 

Anda kini sepatutnya boleh mengakses URL berikut dalam pelayar web anda untuk mengesahkan bahawa API sedang berfungsi: http://127.0.0.1:8080/pets.

6. Sepadukan SwaggerUI

Langkah terakhir ialah menyepadukan SwaggerUI dalam pelayan API. Mula-mula, buat direktori bernama swagger-ui dalam direktori akar projek dan muat turun SwaggerUI di dalamnya Ini boleh dicapai dengan menjalankan arahan berikut:

$ mkdir swagger-ui && cd swagger-ui && wget https://github.com/swagger-api/swagger-ui/archive/v3.32.3.tar.gz && tar xfz v3.32.3.tar.gz --strip-components=1 && rm v3.32.3.tar.gz

Seterusnya, dalam fail main.go API. pelayan Tambahkan kod berikut dalam:

// Setup the SwaggerUI middleware
swaggerUI := http.FileServer(http.Dir("./swagger-ui/dist"))
r.PathPrefix("/docs").Handler(http.StripPrefix("/docs", swaggerUI))

Kod ini mendedahkan direktori dist dalam SwaggerUI sebagai fail sumber statik untuk memaparkan SwaggerUI sebenar.

Kini anda boleh melihat dokumentasi API yang dijana secara automatik dengan melawati URL berikut dalam penyemak imbas anda: http://localhost:8080/docs/index.html.

Kesimpulan

Tidak sukar untuk menggunakan SwaggerUI untuk melaksanakan dokumentasi dalam talian API di Golang, yang membawa kemudahan besar kepada penulisan dan penyelenggaraan dokumentasi API. Dengan menggunakan Swagger, dokumentasi boleh dijana secara automatik untuk API, dan jurutera bahagian belakang serta jurutera bahagian hadapan boleh memahami antara muka API dengan cepat. Ini sangat memudahkan proses pembangunan, ujian dan dokumentasi API, membolehkan pembangun menumpukan lebih pada pelaksanaan logik perniagaan.

Atas ialah kandungan terperinci Menggunakan SwaggerUI untuk melaksanakan dokumentasi dalam talian API di Golang. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!