# OpenAPI & Swagger — REST API Design: Resources, Status Codes and Security

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

> Describe your API with an OpenAPI spec to generate interactive docs, client SDKs and server stubs from one source.

## 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.