توليد Swagger/OpenAPI للغة Go (Golang): go-swagger و oapi-codegen

توليد Swagger/OpenAPI للغة Go (Golang): go-swagger و oapi-codegen

\n\n

يتطلب تطوير خدمات الويب الحديثة بلغة Go مواصفات API صارمة. OpenAPI (المعروف سابقًا باسم Swagger) هو معيار لوصف واجهات RESTful، والذي يسمح بأتمتة إنشاء العملاء والخوادم والوثائق. في نظام Go البيئي، هناك أداتان رئيسيتان لتوليد الكود من مواصفات OpenAPI: go-swagger و oapi-codegen. في هذه المقالة، سنشرح بالتفصيل كلا النهجين، وكيفية تثبيتهما، وتطبيقاتهما العملية.

\n\n

ما هو OpenAPI ولماذا توليد الكود؟

\n

مواصفات OpenAPI (OAS) هي تنسيق ملف (عادةً YAML أو JSON) يصف نقاط النهاية والمعلمات وأنواع البيانات ومخططات الاستجابة لواجهة API الخاصة بك. بدلاً من كتابة المعالجات والنماذج والتحقق يدويًا، يمكنك:

\n

\n
• توليد كود الخادم مع المسارات والبرمجيات الوسيطة.
\n
• توليد SDK للعميل لخدمات أخرى.
\n
• تحديث الوثائق تلقائيًا (Swagger UI).
\n
• تجنب عدم التزامن بين المواصفات والتنفيذ.
\n

\n\n

الأداة رقم 1: go-swagger

\n

go-swagger هي أداة قوية ولكنها أثقل، تدعم ليس فقط التوليد ولكن أيضًا التحقق من صحة المواصفات. إنها مثالية للمشاريع المعقدة ذات الإصدارات.

\n\n

تثبيت go-swagger

\n

# التثبيت عبر go install (Go 1.17+)\ngo install github.com/go-swagger/go-swagger/cmd/swagger@latest\n\n# التحقق من التثبيت\nswagger version

\n\n

توليد الخادم من المواصفات

\n

لنفترض أن لدينا ملف api.yaml:

\n

openapi: "3.0.0"\ninfo:\n  title: Pet Store\n  version: "1.0.0"\npaths:\n  /pets:\n    get:\n      summary: List all pets\n      operationId: listPets\n      responses:\n        '200':\n          description: A list of pets\n          content:\n            application/json:\n              schema:\n                type: array\n                items:\n                  $ref: '#/components/schemas/Pet'\ncomponents:\n  schemas:\n    Pet:\n      type: object\n      properties:\n        id:\n          type: integer\n        name:\n          type: string

\n\n

قم بتنفيذ توليد الخادم:

\n

swagger generate server -f api.yaml -A petstore -t ./gen

\n

بعد التنفيذ، في المجلد ./gen ستظهر:

\n

\n
• restapi/ — المعالجات والمسارات.
\n
• models/ — هياكل البيانات (Pet, Error إلخ).
\n
• cmd/ — نقطة الدخول للتطبيق.
\n

\n\n

مثال على تنفيذ المعالج

\n

package restapi\n\nimport (\n    "net/http"\n    "petstore/gen/models"\n    "petstore/gen/restapi/operations"\n)\n\nfunc configureAPI(api *operations.PetstoreAPI) http.Handler {\n    api.ListPetsHandler = operations.ListPetsHandlerFunc(\n        func(params operations.ListPetsParams) middleware.Responder {\n            pets := []*models.Pet{\n                {ID: 1, Name: "Buddy"},\n                {ID: 2, Name: "Milo"},\n            }\n            return operations.NewListPetsOK().WithPayload(pets)\n        },\n    )\n    return api.Serve(nil)\n}

\n\n

الأداة رقم 2: oapi-codegen

\n

oapi-codegen هو مولد حديث وخفيف وسريع جدًا من فريق DeepMap. يدعم OpenAPI 3.0 ويركز على البساطة. يُوصى به للمشاريع الجديدة.

\n\n

تثبيت oapi-codegen

\n

go install github.com/deepmap/oapi-codegen/v2/cmd/oapi-codegen@latest

\n\n

توليد الأنواع والخادم

\n

نستخدم نفس المواصفات api.yaml. قم بتنفيذ:

\n

oapi-codegen -generate types,server -package petstore api.yaml > petstore.gen.go

\n

العلامة -generate تسمح باختيار ما سيتم توليده:

\n

\n
• types — هياكل Go
\n
• server — كود الخادم
\n