What is swagger.json and it is used in recon for enumerating attacking APIs

Using swagger.json (or its equivalents like swagger.yaml, openapi.json, or /v2/api-docs) is one of the most powerful passive reconnaissance techniques for enumerating and attacking APIs. It reveals the entire API surface, including:

All endpoints (paths)
Allowed HTTP methods
Required request parameters
Authentication schemes (OAuth2, API Key, etc.)
Request/response data models
Server URLs and versions

Let’s dig deep into how this works, including real-world examples, tooling, and code-level origin.

🔍 What is `/swagger.json` or `OpenAPI` spec?

Swagger (now standardized as OpenAPI) is a machine-readable JSON or YAML specification that describes the structure of REST APIs. Most modern frameworks expose it at URLs like:

https://target.com/swagger.json
https://target.com/openapi.json
https://target.com/api-docs
https://target.com/v2/api-docs (Spring Boot)
https://target.com/swagger-ui/ (renders HTML UI)

🛠️ How to Identify It

📌 Step-by-step identification process

Manual Browsing

Try appending common paths:

/swagger.json
/v2/api-docs
/openapi.json
/swagger-ui/
/api/swagger.json
/docs/

Using gau, waybackurls, hakrawler:

gau target.com | grep -iE 'swagger|api-docs|openapi'

Brute Force with ffuf or dirsearch:

ffuf -w common-api-docs.txt -u https://target.com/FUZZ

Intercept JavaScript: Parse .js files for calls to swagger-ui or hardcoded Swagger/OpenAPI paths.

📄 What Does `swagger.json` Look Like?

{
  "openapi": "3.0.0",
  "info": {
    "title": "User Management API",
    "version": "1.0.0"
  },
  "paths": {
    "/users": {
      "get": {
        "summary": "List users",
        "responses": {
          "200": {
            "description": "A list of users"
          }
        }
      },
      "post": {
        "summary": "Create a user",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/User"
              }
            }
          }
        }
      }
    }
  }
}

This gives you:

All endpoint paths (/users)
HTTP methods (GET, POST)
Request/response schemas
Parameter names and types
Authentication requirements

🔬 How Swagger Is Exposed (Code-Level)

🧪 Example: Spring Boot (`springdoc-openapi` or `springfox`)

@OpenAPIDefinition(
  info = @Info(title = "User API", version = "v1")
)
@RestController
@RequestMapping("/users")
public class UserController {
  @GetMapping("/")
  public List<User> listUsers() { ... }

  @PostMapping("/")
  public ResponseEntity<?> addUser(@RequestBody User u) { ... }
}

These annotations generate /v3/api-docs or /v2/api-docs, depending on the library.

🛠 Generation Libraries:

Spring Boot: springdoc-openapi, springfox
Node.js: swagger-jsdoc, express-oas-generator
Django: drf-yasg, django-rest-swagger
Flask: flask-restx, apispec
FastAPI: Native openapi.json and swagger-ui

🧰 Exploitation Value for Bug Bounty / Pentesting

✅ Useful Recon Data

Hidden endpoints not linked in frontend
HTTP methods (e.g., DELETE, PATCH)
Parameters (names, types, required/optional)
Auth info (bearer, apiKey, etc.)
Nested object structures (for BOLA/IDOR)
Enum values & value ranges (for fuzzing)

🚨 Example Exploit Paths

Broken Object Level Authorization (BOLA): If /users/{id} exists with no auth, test GET /users/1, 2, etc.
Insecure Methods: If DELETE /users/{id} is present but frontend doesn’t expose it
Exposed Dev/Test Paths: /debug/, /internal/, /test-api/ in Swagger spec
JWT Scopes Abuse: Swagger may list OAuth2 scopes you didn’t know existed

🛠 Tooling for Swagger Enumeration

Tool	Description
Swagger Editor	Online tool to view/edit Swagger/OpenAPI
Swagger2Postman	Convert spec to Postman collection
Postman	Import `swagger.json`, test APIs
Swagger Parser (Python)	Programmatically extract all paths and methods
Burp Suite Extension	OpenAPI Parser imports specs
nuclei	Template engine to target paths from Swagger
Owasp Amass	Extracts from JS and finds openapi specs

📚 Programmatic Parsing Example

Python using `openapi-spec-validator` and `requests`

import requests
import json

resp = requests.get('https://target.com/swagger.json')
data = resp.json()

for path, methods in data['paths'].items():
    for method in methods:
        print(f"{method.upper()} {path}")

🔒 Mitigation / Hardening

If you are building or securing an API:

Do not expose Swagger in production or control via role-based access
Use Swagger UI only in internal/staging networks
Validate that all exposed paths require proper authorization
Avoid hardcoding sensitive example payloads (e.g., JWTs, passwords)

🧠 Summary

What You Get	Why It Matters
Complete Endpoint List	Full enumeration even if not linked
HTTP Methods	Test for unauthorized access (BOLA)
Input Parameter Schemas	Great for fuzzing/injection
Authentication Scheme	Understand how to bypass or mimic auth
Models and Enum Values	Helps you guess valid inputs

Tags

🔍 What is /swagger.json or OpenAPI spec?