Troubleshooting guide

This guide helps you diagnose and fix common issues when creating, testing, and maintaining OpenAPI documentation. Solutions are organized by problem type with step-by-step resolution instructions.

Quick diagnosis checklist

Is the API running?

# Test basic connectivity
curl http://localhost:8080/customers
# Should return JSON response, not connection error

# Check if Spring Boot started successfully
# Look for "Started RestDemoApplication" in console logs

Is the documentation accessible?

# Test generated documentation endpoints
curl http://localhost:8080/v3/api-docs
curl http://localhost:8080/swagger-ui/index.html

# Both should return content, not 404 errors

Are your examples working?

# Test the simplest documented example
curl -X POST http://localhost:8080/customer \
  -H "Content-Type: application/json" \
  -d '{"id": "TEST001", "name": "Test Customer", "type": "INDIVIDUAL"}'

# Should return "Customer added successfully", not an error

API connectivity issues

Problem: “Connection refused” or “Could not connect”

Symptoms:

curl: (7) Failed to connect to localhost port 8080: Connection refused
Swagger UI shows “Failed to fetch”
Postman shows “Could not get any response”

Causes and solutions:

Application not running

# Start the application
./mvnw spring-boot:run

# Wait for startup message
# Look for: "Started RestDemoApplication in X.XXX seconds"

Wrong port number

# Check which port Spring Boot is using
# Look in startup logs for: "Tomcat started on port(s): 8080"

# If using different port, update your URLs
curl http://localhost:ACTUAL_PORT/customers

Firewall or network issues

# Test localhost specifically
curl http://127.0.0.1:8080/customers

# Check if port is actually open
netstat -an | grep 8080
lsof -i :8080

Problem: “404 Not Found” for API endpoints

Symptoms:

API returns 404 for documented endpoints
Swagger UI shows endpoints but they don’t work

Causes and solutions:

Incorrect base URL

# Correct base URL (no /api prefix)
curl http://localhost:8080/customers

# Not: http://localhost:8080/api/customers

Case sensitivity issues

# Use exact case from documentation
curl http://localhost:8080/customer/CUST001

# Not: http://localhost:8080/Customer/cust001

Missing required headers

# Include Content-Type for POST/PUT requests
curl -X POST http://localhost:8080/customer \
  -H "Content-Type: application/json" \
  -d '{"id": "TEST001", "name": "Test", "type": "INDIVIDUAL"}'

Authentication and authorization errors

Problem: “401 Unauthorized” responses

Symptoms:

DELETE requests return 401
Error message: “Full authentication is required”

Solutions:

Add authentication for protected endpoints

# DELETE endpoints require admin authentication
curl -u testadmin:admin123 -X DELETE http://localhost:8080/customer/CUST001

# Other endpoints are public (no auth needed)
curl http://localhost:8080/customers

Verify credentials are correct

# Demo admin credentials
Username: testadmin
Password: admin123

# Demo user credentials (limited access)
Username: testuser
Password: user123

Check authentication header format

# Correct Basic Auth header
curl -H "Authorization: Basic dGVzdGFkbWluOmFkbWluMTIz" \
  -X DELETE http://localhost:8080/customer/CUST001

# Generate Base64 encoding
echo -n "testadmin:admin123" | base64

Problem: “403 Forbidden” responses

Symptoms:

Request is authenticated but still rejected
Error message mentions “Access Denied”

Solution:

# User role has limited permissions
# Use admin credentials for DELETE operations
curl -u testadmin:admin123 -X DELETE http://localhost:8080/customer/CUST001

# Regular user credentials work for other operations
curl -u testuser:user123 http://localhost:8080/customers

Data validation errors

Problem: “400 Bad Request” with validation messages

Symptoms:

POST/PUT requests return 400
Error mentions invalid data format

Common validation issues:

Invalid customer ID format

# Wrong - doesn't follow CUSTXXX pattern
curl -X POST http://localhost:8080/customer \
  -H "Content-Type: application/json" \
  -d '{"id": "123", "name": "Test", "type": "INDIVIDUAL"}'

# Correct - follows CUSTXXX pattern
curl -X POST http://localhost:8080/customer \
  -H "Content-Type: application/json" \
  -d '{"id": "CUST001", "name": "Test", "type": "INDIVIDUAL"}'

Invalid customer type

# Wrong - INVALID_TYPE not allowed
curl -X POST http://localhost:8080/customer \
  -H "Content-Type: application/json" \
  -d '{"id": "CUST001", "name": "Test", "type": "INVALID_TYPE"}'

# Correct - use valid enum value
curl -X POST http://localhost:8080/customer \
  -H "Content-Type: application/json" \
  -d '{"id": "CUST001", "name": "Test", "type": "INDIVIDUAL"}'

# Valid types: INDIVIDUAL, BUSINESS, VIP, PREMIUM

Missing required fields

# Wrong - missing required 'name' field
curl -X POST http://localhost:8080/customer \
  -H "Content-Type: application/json" \
  -d '{"id": "CUST001", "type": "INDIVIDUAL"}'

# Correct - includes all required fields
curl -X POST http://localhost:8080/customer \
  -H "Content-Type: application/json" \
  -d '{"id": "CUST001", "name": "Required Name", "type": "INDIVIDUAL"}'

Problem: “409 Conflict” - duplicate resource

Symptoms:

POST returns 409 when creating customers
Error message mentions “already exists”

Solution:

# Use unique customer IDs
curl -X POST http://localhost:8080/customer \
  -H "Content-Type: application/json" \
  -d '{"id": "UNIQUE001", "name": "Unique Customer", "type": "INDIVIDUAL"}'

# Check existing customers first
curl http://localhost:8080/customers

# Delete existing customer if needed (requires admin auth)
curl -u testadmin:admin123 -X DELETE http://localhost:8080/customer/CUST001

Documentation generation issues

Problem: Swagger UI shows “Failed to load API definition”

Symptoms:

Swagger UI page loads but shows error message
Cannot access interactive documentation

Solutions:

Check OpenAPI endpoint directly

# Test if spec is being generated
curl http://localhost:8080/v3/api-docs

# Should return JSON, not HTML error page

Verify SpringDoc configuration

// Check that OpenApiConfig.java exists and is properly configured
// Look for @Configuration and @Bean annotations

Clear browser cache

# Hard refresh Swagger UI page
# Chrome/Firefox: Cmd/Ctrl + Shift + R
# Safari: Cmd + Option + R

Problem: Generated documentation missing endpoints

Symptoms:

Some controller methods don’t appear in Swagger UI
Generated spec is incomplete

Solutions:

Check method annotations

// Ensure methods have proper Spring Web annotations
@GetMapping("/customers")  // Required for endpoint discovery
@PostMapping("/customer")  // Required for endpoint discovery

Verify controller is component-scanned

// Controller must be in scanned package
// Check @RestController annotation exists
@RestController
public class CustomerAPIService {
    // Methods here will be documented
}

Check for @Hidden annotations

// Remove @Hidden if endpoint should be documented
// @Hidden  // Remove this line
@GetMapping("/customers")
public ResponseEntity<List<Customer>> getCustomers() {
    // Implementation
}

YAML specification problems

Problem: “Invalid OpenAPI specification” errors

Symptoms:

Swagger Editor shows validation errors
Tools refuse to import specification

Common YAML syntax issues:

Indentation errors

# Wrong - inconsistent indentation
info:
  title: My API
   version: 1.0.0  # Extra space causes error

# Correct - consistent 2-space indentation
info:
  title: My API
  version: 1.0.0

Missing required fields

# Wrong - missing required 'info' section
openapi: 3.0.1
paths:
  /test: {}

# Correct - includes required sections
openapi: 3.0.1
info:
  title: Test API
  version: 1.0.0
paths:
  /test: {}

Invalid references

# Wrong - schema doesn't exist
responses:
  '200':
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/NonexistentSchema'

# Correct - ensure referenced schema exists
components:
  schemas:
    Customer:
      type: object
paths:
  /customers:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'

Problem: Examples don’t work when tested

Symptoms:

YAML validates but examples fail
Documented examples return errors

Solution process:

Test every documented example

# Copy exact example from documentation
curl -X POST http://localhost:8080/customer \
  -H "Content-Type: application/json" \
  -d '{
    "id": "CUST001",
    "name": "Alice Johnson",
    "type": "VIP"
  }'

# If this fails, update the documentation example

Validate against running API

# Test required vs optional fields
# Minimal example (required fields only)
curl -X POST http://localhost:8080/customer \
  -H "Content-Type: application/json" \
  -d '{"id": "MIN001", "name": "Minimal", "type": "INDIVIDUAL"}'

# Complete example (all fields)
curl -X POST http://localhost:8080/customer \
  -H "Content-Type: application/json" \
  -d '{
    "id": "FULL001",
    "name": "Full Example",
    "phone": "555-0123",
    "type": "VIP",
    "address": {
      "street": "123 Main St",
      "city": "New York",
      "state": "NY",
      "zipCode": "10001",
      "country": "USA"
    }
  }'

Postman collection issues

Problem: “Could not get any response” in Postman

Symptoms:

Requests timeout or fail in Postman
Same requests work with cURL

Solutions:

Check Postman environment variables

# Verify baseUrl variable is set correctly
# Environment: Development
# Variable: baseUrl
# Value: http://localhost:8080 (no trailing slash)

Disable SSL certificate verification

# Postman Settings → General
# Turn OFF "SSL certificate verification"
# (For local development only)

Check proxy settings

# Postman Settings → Proxy
# Turn OFF "Use the system proxy"
# Or configure correctly for your network

Problem: Authentication not working in Postman

Symptoms:

DELETE requests return 401 in Postman
Authentication works with cURL

Solutions:

Set collection-level authentication

# Right-click collection → Edit
# Authorization tab → Type: Basic Auth
# Username: testadmin
# Password: admin123

Set request-level authentication

# Individual request → Authorization tab
# Type: Basic Auth
# Username: testadmin
# Password: admin123

Check environment variables for auth

# Add to environment:
# adminUsername: testadmin
# adminPassword: admin123

# Use in authorization:
# Username: 
# Password: 

Performance and timeout issues

Problem: Slow API responses or timeouts

Symptoms:

API takes a long time to respond
Requests timeout before completing

Solutions:

Check database performance

# For H2 database, check file system
ls -la data/customers.*

# Large database files may slow queries
# Consider resetting for development
rm -rf data/customers.* && ./mvnw spring-boot:run

Increase timeout in tools

# Postman: Settings → General → Request timeout
# Set to 30000ms (30 seconds) for development

# cURL: Add timeout parameter
curl --max-time 30 http://localhost:8080/customers

Optimize queries

# Use pagination for large datasets
curl "http://localhost:8080/customers?size=10"

# Use specific search instead of getting all
curl "http://localhost:8080/customers/search?name=Alice"

Version control and collaboration issues

Problem: Documentation out of sync with API

Symptoms:

Examples work locally but fail for teammates
Documentation doesn’t match current API behavior

Solutions:

Establish update process

# After API changes, update documentation
curl http://localhost:8080/v3/api-docs.yaml > current-spec.yaml
git diff previous-spec.yaml current-spec.yaml

# Update manual documentation to match

Test documentation after changes

# Create test script to validate all examples
#!/bin/bash
echo "Testing documented examples..."

# Test each documented example
curl -X POST http://localhost:8080/customer \
  -H "Content-Type: application/json" \
  -d @documented-example.json

echo "All examples tested successfully"

Use consistent environments

# Ensure everyone uses same demo data
# Create setup script for consistent state
./reset-demo-data.sh

Getting help and additional resources

When to escalate issues

Contact developers when:

SpringDoc annotations need updates
API behavior doesn’t match documented examples
New endpoints missing from generated documentation

Contact system administrators when:

Network connectivity issues persist
Port conflicts cannot be resolved
Database performance problems continue

Useful debugging commands

# Check Java and Maven versions
java -version
mvn -version

# Check network connectivity
ping localhost
telnet localhost 8080

# Check process information
ps aux | grep spring
lsof -i :8080

# Check application logs
./mvnw spring-boot:run | grep ERROR
./mvnw spring-boot:run | grep WARN

Online validation tools

OpenAPI Validator: https://validator.swagger.io/
YAML Validator: https://yamlchecker.com/
JSON Validator: https://jsonlint.com/
Swagger Editor: https://editor.swagger.io/

This troubleshooting guide covers the most common issues encountered when working with API documentation. When in doubt, start with the quick diagnosis checklist and work through the systematic solutions provided.