# OpenAPI और Swagger — REST API Design: Resources, Status Codes और Security

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

> एक ही source से interactive docs, client SDKs और server stubs बनाने के लिए OpenAPI spec से अपनी 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 से भटक जाते हैं। जहाँ संभव हो, स्पेक को कोड एनोटेशन या टेस्ट से जनरेट करें ताकि यह चुपचाप बासी न हो जाए।