OpenAPI और Swagger

एक स्पेक, कई उपयोग

OpenAPI (पहले Swagger) एक YAML/JSON फ़ॉर्मैट है जो हर एंडपॉइंट, पैरामीटर, रिक्वेस्ट/रिस्पॉन्स आकार और ऑथ आवश्यकता का वर्णन करता है। इस एक स्पेक से आप इंटरैक्टिव डॉक्स, क्लाइंट SDK और सर्वर स्टब जनरेट कर सकते हैं।

एक छोटा टुकड़ा

हर पाथ अपने मेथड, पैरामीटर और संभावित रिस्पॉन्स दस्तावेज़ करता है।

paths:
  /orders/{id}:
    get:
      summary: Get an order by id
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        '200': { description: Order found }
        '404': { description: Order not found }

हाथ से कॉपी नहीं, जनरेट रखें

हाथ से बनाए रखे डॉक्स कुछ हफ़्तों में असली API से भटक जाते हैं। जहाँ संभव हो, स्पेक को कोड एनोटेशन या टेस्ट से जनरेट करें ताकि यह चुपचाप बासी न हो जाए।