Here’s a comprehensive, minimal, and realistic OpenAPI 3.0 specification that demonstrates OAuth 2.0 security using the Authorization Code flow with PKCE (ideal for web and mobile applications) and the Client Credentials flow (for machine-to-machine communication).

---

✅ Sample: petstore-oauth2.yaml

openapi: 3.0.3
info:
  title: Secure Pet Store API
  version: 1.0.0
  description: A sample API secured with OAuth 2.0

servers:
  - url: https://api.petstore.example.com/v1
    description: Production server

paths:
  /pets:
    get:
      summary: List all pets
      security:
        - PetStoreAuth:
            - read:pets
      responses:
        '200':
          description: A list of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden (insufficient scope)

    post:
      summary: Create a new pet
      security:
        - PetStoreAuth:
            - write:pets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewPet'
      responses:
        '201':
          description: Pet created
        '401':
          description: Unauthorized
        '403':
          description: Forbidden (insufficient scope)

  /pets/{petId}:
    get:
      summary: Get a specific pet
      parameters:
        - name: petId
          in: path
          required: true
          schema:
            type: integer
      security:
        - PetStoreAuth:
            - read:pets
      responses:
        '200':
          description: Pet details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        '404':
          description: Pet not found

components:
  schemas:
    Pet:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        species:
          type: string
      required:
        - id
        - name

    NewPet:
      type: object
      properties:
        name:
          type: string
        species:
          type: string
      required:
        - name

  securitySchemes:
    PetStoreAuth:
      type: oauth2
      description: OAuth 2.0 security using Authorization Code + Client Credentials flows
      flows:
        authorizationCode:
          authorizationUrl: https://auth.petstore.example.com/oauth/authorize
          tokenUrl: https://auth.petstore.example.com/oauth/token
          scopes:
            read:pets: Read access to pets
            write:pets: Write access to pets
          # PKCE is implied for public clients (no client_secret)
        clientCredentials:
          tokenUrl: https://auth.petstore.example.com/oauth/token
          scopes:
            read:pets: Read access to pets
            write:pets: Write access to pets

# Apply global security (optional)
# security:
#   - PetStoreAuth: []

---

🔑 Key Security Highlights

1. Per-Operation Scope Enforcement
   • GET /pets requires read:pets
   • POST /pets requires write:pets
2. Two OAuth 2.0 Flows Defined
   • authorizationCode: For user-facing apps (web/mobile). Supports PKCE (no client secret needed for public clients).
   • clientCredentials: For backend services (uses client ID + secret).
3. Clear Scope Definitions
   Scopes are fine-grained (read:pets, write:pets) — enabling least-privilege access.
4. Realistic Endpoints
   Includes path parameters, request bodies, and common HTTP status codes (401, 403, 404).
5. No Global Security (Optional)
   Security is applied per-path, allowing public endpoints if needed (e.g., /health).

---

🛠️ How an API Gateway Would Use This

• Kong / AWS API Gateway / Apigee can auto-generate OAuth 2.0 policies from this spec.
• During deployment, the gateway:
  • Validates incoming JWTs or introspects opaque tokens
  • Checks for required scopes in the token’s scope claim
  • Rejects requests with 403 if scopes are missing
• Audit logs can include scope, client_id, and sub (user ID)

---

💡 Testing Tips

• Use Postman or curl with a valid access token:bash12
• Validate token structure at jwt.io
• Ensure your IdP (e.g., Auth0, Okta, Keycloak) issues tokens with correct scope and aud claims