# OpenAPI और Swagger — रेस्ट एपीआई डिज़ाइन

Source: https://www.geekswithgeeks.com/hi/restapi/api-openapi-swagger

> API को एक मशीन-पठनीय स्पेक में वर्णित करना जो दस्तावेज़ीकरण भी करता है।

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

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

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

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

```yaml
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 से भटक जाते हैं। जहाँ संभव हो, स्पेक को कोड एनोटेशन या टेस्ट से जनरेट करें ताकि यह चुपचाप बासी न हो जाए।