Go (Golang) के लिए Swagger/OpenAPI जनरेशन: go-swagger और oapi-codegen

Go (Golang) के लिए Swagger/OpenAPI जनरेशन: go-swagger और oapi-codegen

Go में आधुनिक वेब-सर्विसेज डेवलप करने के लिए API की सख्त स्पेसिफिकेशन ज़रूरी है। OpenAPI (जिसे पहले Swagger के नाम से जाना जाता था) RESTful इंटरफेस का वर्णन करने का एक मानक है, जो क्लाइंट, सर्वर और डॉक्यूमेंटेशन को ऑटोमेटेड तरीके से बनाने में मदद करता है। Go इकोसिस्टम में OpenAPI स्पेसिफिकेशन से कोड जनरेट करने के लिए दो मुख्य टूल हैं: go-swagger और oapi-codegen। इस लेख में हम दोनों तरीकों, उनकी स्थापना और व्यावहारिक उपयोग पर विस्तार से चर्चा करेंगे।

OpenAPI क्या है और कोड क्यों जनरेट करें?

OpenAPI Specification (OAS) एक फ़ाइल फ़ॉर्मेट (आमतौर पर YAML या JSON) है जो आपके API के एंडपॉइंट, पैरामीटर, डेटा टाइप और रिस्पॉन्स स्कीमा का वर्णन करता है। मैन्युअल रूप से हैंडलर, मॉडल और वैलिडेशन लिखने के बजाय, आप यह कर सकते हैं:

• रूट्स और मिडलवेयर के साथ सर्वर साइड कोड जनरेट करें।
• अन्य सर्विसेज के लिए क्लाइंट SDK जनरेट करें।
• डॉक्यूमेंटेशन (Swagger UI) को ऑटोमेटिकली अपडेट करें।
• स्पेसिफिकेशन और इम्प्लीमेंटेशन के बीच असंगति से बचें।

टूल #1: go-swagger

go-swagger एक शक्तिशाली लेकिन भारी टूल है जो स्पेसिफिकेशन जनरेशन के साथ-साथ वैलिडेशन भी सपोर्ट करता है। यह वर्जनिंग वाले जटिल प्रोजेक्ट्स के लिए आदर्श है।

go-swagger की स्थापना

# go install के माध्यम से स्थापना (Go 1.17+)
go install github.com/go-swagger/go-swagger/cmd/swagger@latest

# स्थापना की जाँच
swagger version

स्पेसिफिकेशन से सर्वर जनरेशन

मान लीजिए हमारे पास api.yaml फ़ाइल है:

openapi: "3.0.0"
info:
  title: Pet Store
  version: "1.0.0"
paths:
  /pets:
    get:
      summary: सभी पालतू जानवरों की सूची
      operationId: listPets
      responses:
        '200':
          description: पालतू जानवरों की सूची
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

सर्वर जनरेशन चलाएँ:

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

इसे चलाने के बाद ./gen फ़ोल्डर में ये फ़ाइलें बनेंगी:

• restapi/ — हैंडलर और रूट्स।
• models/ — डेटा स्ट्रक्चर (Pet, Error आदि)।
• cmd/ — एप्लिकेशन का एंट्री पॉइंट।

हैंडलर इम्प्लीमेंटेशन का उदाहरण

package restapi

import (
    "net/http"
    "petstore/gen/models"
    "petstore/gen/restapi/operations"
)

func configureAPI(api *operations.PetstoreAPI) http.Handler {
    api.ListPetsHandler = operations.ListPetsHandlerFunc(
        func(params operations.ListPetsParams) middleware.Responder {
            pets := []*models.Pet{
                {ID: 1, Name: "बडी"},
                {ID: 2, Name: "माइलो"},
            }
            return operations.NewListPetsOK().WithPayload(pets)
        },
    )
    return api.Serve(nil)
}

टूल #2: oapi-codegen

oapi-codegen DeepMap टीम का एक आधुनिक, हल्का और बहुत तेज़ जनरेटर है। यह OpenAPI 3.0 को सपोर्ट करता है और मिनिमलिज़्म पर फोकस करता है। नए प्रोजेक्ट्स के लिए इसकी सिफारिश की जाती है।

oapi-codegen की स्थापना

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

टाइप्स और सर्वर जनरेशन

उसी api.yaml स्पेसिफिकेशन का उपयोग करें। यह चलाएँ:

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

-generate फ़्लैग से आप चुन सकते हैं कि क्या जनरेट करना है:

• types — स्कीमा के लिए Go स्ट्रक्चर।
• server — सर्वर इंटरफेस।
• client — क्लाइंट कोड।