Menggunakan SwaggerUI dalam Golang untuk automasi dokumentasi dalam talian API

Menggunakan SwaggerUI di Golang untuk automasi dokumentasi dalam talian API

Penggunaan API (Antaramuka Pengaturcaraan Aplikasi) telah menjadi elemen yang diperlukan dalam pembangunan aplikasi moden. API menjadikan pemisahan bahagian hadapan dan belakang, perkhidmatan mikro dan aplikasi awan lebih mudah. Walau bagaimanapun, API yang baik bukan sahaja melaksanakan fungsi, tetapi mesra pengguna dan mudah digunakan. Atas sebab ini, API yang didokumenkan menjadi semakin penting. Manfaat dokumentasi dalam talian ialah anda boleh mempelajari tentang API sebelum mengendalikannya.

Dalam artikel ini, kami akan memperkenalkan cara menggunakan SwaggerUI untuk merekodkan dokumentasi API dan cara mengautomasikan proses ini di Golang supaya lebih mudah untuk mengekalkan dan menyediakan dokumentasi yang boleh dibaca supaya pasukan dan rakan kongsi lain dapat memahami anda. API.

SwaggerUI ialah alat yang popular untuk mencipta dokumentasi untuk API, menjana dokumentasi API interaktif, menerangkan API dalam cara visual dan boleh menjana kedua-dua dokumentasi yang boleh dibaca manusia dan JSON atau YAML yang boleh dibaca oleh mesin. SwaggerUI berintegrasi dengan banyak bahasa pengaturcaraan, termasuk Golang.

Pertama, anda perlu menggunakan Swag, pelaksanaan Golang SwaggerUI. Swag ialah alat dokumentasi API automatik yang menggabungkan anotasi bahasa Go dan anotasi Swagger untuk menjana dokumen Swagger 2.0 secara automatik.

Langkah 1: Pasang Swag

Muat turun dan pasang Swag menggunakan arahan berikut dalam terminal/cmd:

go get -u github.com/swaggo/swag/cmd/swag

Langkah 2: Tambah ulasan Swagger dalam kod

Tambahkan anotasi Swagger pada kod anda untuk menerangkan API.

Tambah anotasi Swagger dalam ulasan di atas fungsi pengendali HTTP, contohnya:

// GetByID godoc
// @Summary Get user details by ID
// @Description Get user details by ID
// @Tags user
// @Accept json
// @Produce json
// @Param id path int true "User ID"
// @Success 200 {object} model.User
// @Failure 400 {object} ErrorResponse
// @Router /users/{id} [get]
func GetByID(c *gin.Context) {
    //…code here…
}

Langkah 3: Jana fail JSON Swagger

Gunakan arahan berikut dalam akar asas kod Hasilkan fail JSON Swagger dalam:

swag init

Perintah ini akan menggunakan anotasi Swagger dalam kod dan menjana fail JSON Swagger. Anda juga boleh menambahkannya dalam Makefile projek anda.

Langkah 4: Sepadukan SwaggerUI

Swag menggunakan SwaggerUI sebagai bahagian hadapan untuk memaparkan dokumen API dalam penyemak imbas Kami perlu membalikkan proksi fail dalam SwaggerUI ke aplikasi kami.

Anggapkan aplikasi Golang kami berjalan pada port 8080. Versi SwaggerUI yang akan kami gunakan ialah v3.31.1. Kami boleh memuat turunnya daripada halaman rasmi SwaggerUI GitHub dengan:

curl -L https://github.com/swagger-api/swagger-ui/archive/v3.31.1.tar.gz -o swagger-ui.tar.gz
tar -xf swagger-ui.tar.gz

Ini akan menjana folder swagger-ui dalam direktori tempatan, yang mengandungi semua fail SwaggerUI. Kami akan menggunakan nginx sebagai pelayan proksi terbalik (anda boleh menggunakan Apache, Caddy, dll.), mulakan nginx dengan arahan berikut dalam terminal/cmd:

nginx -c /path/to/nginx.conf

Dalam fail nginx.conf kita perlu menambah berikut:

http {
  server {
    listen 8081; # 访问静态文件的端口
    server_name _;
    root /path/to/swagger-ui/dist;

    location / {
      try_files $uri $uri/ @go;
    }

    location @go {
      proxy_redirect off;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_pass http://127.0.0.1:8080; # 代理请求的端口
    }

    location /swagger-ui/ {
      try_files $uri $uri/ =404;
    }
  }
}

Dalam konfigurasi nginx di atas, kami menambah folder SwaggerUI statik /swagger-ui/dist direktori ke direktori root pelayan nginx sebagai fail statik dan kami proksi ke localhost:8080 (aplikasi kami sendiri ) dimajukan ke port yang didengari oleh port 8081. Kami melihat dan menggunakan SwaggerUI dengan melawati http://localhost:8081/swagger-ui/.

Langkah 5: Lihat dokumentasi API

Lawati http://localhost:8081/swagger-ui/ dalam penyemak imbas, aplikasi SwaggerUI akan memaparkan fail statik SwaggerUI yang muncul dalam akar folder direktori. Anda boleh menemui senarai semua API yang didokumentasikan dengan baik pada halaman ini. Klik pada dokumentasi API yang anda mahu lihat untuk dipaparkan di sebelah kanan. Laman web ini menyediakan antara muka mesra pengguna API untuk menguji dan melihat dokumentasi API secara langsung pada API. Semasa proses ini, GUI memaparkan maklumat terperinci yang diekstrak secara automatik oleh anotasi Swagger, seperti menyediakan parameter API ini, maklumat badan, versi API, format API, dll. Ini akan sangat menjimatkan masa dan tenaga anda dalam menulis dokumen.

Kesimpulan

Dokumentasi API ialah alat penting dalam proses reka bentuk dan pembangunan API, jadi kami perlu mempertimbangkan API yang didokumenkan semasa membina aplikasi. Menggunakan alat automasi Swag, kami boleh mengautomasikan dokumentasi API dengan mudah di Golang. Ia juga sangat mudah untuk menggunakan SwaggerUI sebagai alat visualisasi untuk melihat dan menguji API yang didokumenkan. Ini akan membantu pasukan lain dan rakan kerjasama serta memudahkan mereka memahami API kami.

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