# OpenAPI & Swagger — REST API Design

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

> Describing an API in a machine-readable spec that also documents it.

## One spec, many uses

**OpenAPI** (formerly Swagger) is a YAML/JSON format describing every endpoint, parameter, request/response shape, and auth requirement. From that single spec you can generate interactive docs, client SDKs, and server stubs.

## A tiny slice

Every path documents its methods, parameters, and possible responses.

```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 }
```

## Keep it generated, not hand-copied

Hand-maintained docs drift from the real API within weeks. Where possible, generate the spec from code annotations or tests so it can't silently go stale.