توليد Swagger/OpenAPI لـ Go (Golang): دليل شامل

توليد Swagger/OpenAPI لـ Go (Golang)

عند تطوير خدمات الويب بلغة Go (Golang)، فإن إحدى المهام الرئيسية هي إنشاء وثائق API عالية الجودة ومحدثة. أصبح Swagger (المعروف الآن باسم OpenAPI) المعيار الصناعي لوصف واجهات RESTful. في هذه المقالة، سنستعرض الأدوات الرئيسية لتوليد مواصفات OpenAPI في نظام Go البيئي، وطريقة تثبيتها، وإعدادها، وتطبيقها العملي.

لماذا تعتبر OpenAPI مهمة لمطور Go؟

تتيح OpenAPI إنشاء وصف قابل للقراءة آليًا لواجهة API الخاصة بك، والذي يمكن استخدامه من أجل:

• التوليد التلقائي للمكتبات العميلة بلغات مختلفة
• إنشاء وثائق تفاعلية (Swagger UI)
• التحقق من صحة الطلبات الواردة والصادرة
• اختبار API باستخدام أدوات مثل Postman أو Insomnia

المكتبات الرئيسية لتوليد OpenAPI في Go

1. swaggo/swag — الخيار الأكثر شيوعًا

مكتبة swaggo/swag هي المعيار الفعلي لتوليد وثائق Swagger في Go. تعمل بناءً على التعليقات التوضيحية في تعليقات الكود.

التثبيت:

go get -u github.com/swaggo/swag/cmd/swaggo get -u github.com/swaggo/gin-swagger  // لإطار Gingo get -u github.com/swaggo/files

مثال على الاستخدام مع Gin:

package main

import (    "github.com/gin-gonic/gin"    "github.com/swaggo/gin-swagger"    "github.com/swaggo/files"    _ "your-module/docs" // الحزمة المُنشأة)

// @title           My API// @version         1.0// @description     مثال على API بلغة Go مع Swagger// @host            localhost:8080// @BasePath        /api/v1

func main() {    r := gin.Default()        r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))        r.GET("/api/v1/users", GetUsers)    r.Run(":8080")}

// GetUsers تُرجع قائمة المستخدمين// @Summary      الحصول على قائمة المستخدمين// @Description  تُرجع جميع مستخدمي النظام// @Tags         users// @Accept       json// @Produce      json// @Success      200  {array}   User// @Router       /users [get]func GetUsers(c *gin.Context) {    users := []User{{ID: 1, Name: "إيفان"}}    c.JSON(200, users)}

type User struct {    ID   int    `json:"id" example:"1"`    Name string `json:"name" example:"إيفان"`}

بعد كتابة الكود، قم بتنفيذ الأمر:

swag init

سيؤدي هذا إلى إنشاء مجلد docs يحتوي على ملفي swagger.json و swagger.yaml.

2. go-swagger — أداة قوية ولكنها أكثر تعقيدًا

توفر go-swagger ليس فقط توليد الوثائق من الكود، بل أيضًا العملية العكسية - توليد الكود من المواصفات.

التثبيت:

go get -u github.com/go-swagger/go-swagger/cmd/swagger

مثال على توليد خادم من المواصفات:

swagger generate server -f ./swagger.yaml -A my-api

توليد الوثائق من الكود:

// swagger:route GET /users users listUsers// تُرجع قائمة المستخدمين.// responses://   200: usersResponse

func ListUsersHandler(w http.ResponseWriter, r *http.Request) {    // التنفيذ}

3. oapi-codegen — نهج حديث مع توليد الكود

تتيح مكتبة oapi-codegen توليد الأنواع، والنماذج الأولية للخادم، والعملاء بناءً على مواصفات OpenAPI.

التثبيت:

go get -u github.com/deepmap/oapi-codegen/cmd/oapi-codegen

مثال على الاستخدام:

أولاً، قم بإنشاء ملف api.yaml:

openapi: "3.0.0"info:  title: My API  version: "1.0"paths:  /users:    get:      oper