Home / Testing and validation guide

Testing and validation guide

This guide teaches you how to systematically test API documentation created through either the generated (code-first) or manual YAML writing (design-first) approaches. You’ll learn to ensure documentation accuracy, identify gaps, and maintain quality over time.

Duration: 45-60 minutes Prerequisites: Completed either the Generated Documentation Guide or Manual YAML Writing Guide

Getting started with testing

Access the documentation environment

Before testing, ensure you have access to all documentation tools. Start the application and verify the documentation endpoints are accessible:

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

# Verify API is running
curl http://localhost:8080/customers
# Should return: {"content":[],"page":0,"size":10,...}

# Access documentation endpoints
# Interactive Documentation: http://localhost:8080/swagger-ui/index.html
# OpenAPI Specification (JSON): http://localhost:8080/v3/api-docs
# OpenAPI Specification (YAML): http://localhost:8080/v3/api-docs.yaml

Understanding the documentation flow

The testing workflow varies depending on your documentation approach:

Generated Documentation Testing:
Code Annotations → SpringDoc → OpenAPI Spec → Test Examples → Verify Accuracy

Manual YAML Testing:
YAML Specification → Validation → Test Against API → Update Specification

Accuracy testing

Test that your documentation’s core examples work exactly as documented.

Test 1: document examples work as-is

For generated documentation:

# Test the exact example from @Parameter annotation
curl -X POST http://localhost:8080/customer \
  -H "Content-Type: application/json" \
  -d '{
    "id": "CUST001",
    "name": "Alice Johnson",
    "address": {
      "street": "123 Main St",
      "city": "New York",
      "state": "NY",
      "zipCode": "10001",
      "country": "USA"
    },
    "phone": "555-0123",
    "type": "VIP"
  }'

# Expected: "Customer added successfully"

For manual YAML documentation:

# Test every example in your YAML file
# Use the exact JSON from your 'example' or 'examples' sections
curl -X POST http://localhost:8080/customer \
  -H "Content-Type: application/json" \
  -d @your-documented-example.json

# Verify response matches documented response

Testing tools integration

Choose the testing approach that best fits your workflow and team preferences.

Option 1: systematic testing with Postman

Set up Postman collection:

Quick start (Use pre-built collection):

# Import the pre-built collection
# File: api-assets/postman/Customer-Management-API.postman_collection.json
# Environment: api-assets/postman/Development.postman_environment.json

# Run complete test suite
postman collection run Customer-Management-API.postman_collection.json \
  --environment Development.postman_environment.json

Build from scratch: Follow the detailed Postman setup guide for step-by-step collection creation with authentication, error testing, and best practices.

Export and share: Use the Postman export guide for professional collection sharing, version control, and team collaboration.

Option 2: Swagger UI interactive testing

Testing workflow:

  1. Navigate to Swagger UI: http://localhost:8080/swagger-ui/index.html
  2. Select an endpoint to test
  3. Fill in parameters using provided examples
  4. Execute the request via “Try it out”
  5. Verify response matches documented format
  6. Test error scenarios with invalid inputs

What to verify:

  • Examples are pre-filled correctly
  • Response formats match documentation
  • Error messages are accurate
  • All endpoints are properly organized

Option 3: automated testing scripts

Create test script:

#!/bin/bash
# api-test-suite.sh

echo "Starting API Documentation Test Suite..."

# Test 1: Basic connectivity
echo "Test 1: API connectivity"
if curl -s http://localhost:8080/customers > /dev/null; then
    echo "✓ API is accessible"
else
    echo "✗ API is not accessible"
    exit 1
fi

# Test 2: Create customer with documented example
echo "Test 2: Create customer"
RESPONSE=$(curl -s -X POST http://localhost:8080/customer \
  -H "Content-Type: application/json" \
  -d '{"id": "TEST001", "name": "Test Customer", "type": "INDIVIDUAL"}')

if [[ $RESPONSE == "Customer added successfully" ]]; then
    echo "✓ Customer creation works as documented"
else
    echo "✗ Customer creation failed: $RESPONSE"
fi

# Add more tests...
echo "Test suite completed."

Validation against different documentation approaches

The validation process differs depending on whether you created generated or manual documentation.

Testing manual YAML documentation

YAML validation process:

  1. Validate syntax: Use online validators or editors
  2. Test examples: Run every documented example against the API
  3. Check references: Verify all $ref links work correctly

Validation commands:

# Validate YAML syntax and OpenAPI compliance
swagger-codegen validate -i your-manual-spec.yaml

# Test against running API
npm install -g dredd
dredd your-manual-spec.yaml http://localhost:8080

Online validation (No setup required):

  • Swagger Editor: https://editor.swagger.io/
  • OpenAPI Validator: https://validator.swagger.io/
  • YAML Checker: https://yamlchecker.com/

Testing generated documentation

Generated documentation checklist:

  1. Verify annotations work: Check that @Operation, @ApiResponse, @Parameter annotations appear correctly
  2. Test auto-generation: Confirm spec updates when code changes
  3. Validate examples: Ensure annotation examples work in practice

Export and validation:

# Export current specification for testing
curl http://localhost:8080/v3/api-docs.yaml > current-spec.yaml

# Test the exported specification
swagger-codegen validate -i current-spec.yaml

# Import into external tools for testing
# Postman: File → Import → Upload current-spec.yaml

Documentation export and sharing validation

Testing how well your documentation works outside its original environment is crucial for API user success.

Export testing

Test documentation portability:

# Export OpenAPI specification
curl http://localhost:8080/v3/api-docs > customer-api.json
curl http://localhost:8080/v3/api-docs.yaml > customer-api.yaml

# Validate exported files work in external tools
# Import into Postman, Insomnia, or other API testing tools
# Verify all endpoints and examples transfer correctly

External tool validation:

  1. Postman collection generation: Import YAML and test all endpoints
  2. External editor testing: Load specification in Swagger Editor
  3. Documentation generation: Create static HTML docs and verify content

Documentation maintenance testing

Ongoing testing ensures your documentation remains accurate as your API evolves.

Regression testing

After API changes:

# 1. Test all previously working examples still work
# 2. Test that new functionality is properly documented
# 3. Verify deprecated features are marked appropriately
# 4. Check that breaking changes are clearly documented

# Create regression test suite
./test-all-documented-examples.sh

Change management workflow

Documentation update process:

Code Change → Auto-generation → Writer Review → Testing → Publication
     ↓              ↓              ↓            ↓          ↓
Developer      SpringDoc      Tech Writer   Testing     Git/Deploy

Testing checklist for updates:

  • Updated descriptions are accurate
  • New examples work correctly
  • Modified error responses are documented
  • Parameter documentation is complete
  • Interactive testing in Swagger UI passes
  • Example validation succeeds
  • Error scenario verification works

Continuous integration

Automated testing setup:

# .github/workflows/docs-test.yml
name: Documentation Testing
on: [push, pull_request]
jobs:
  test-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Setup Java
        uses: actions/setup-java@v2
        with:
          java-version: '17'
      - name: Start API
        run: ./mvnw spring-boot:run &
      - name: Wait for API
        run: sleep 30
      - name: Test Documentation Examples
        run: ./api-test-suite.sh
      - name: Export Updated Specification
        run: curl http://localhost:8080/v3/api-docs.yaml > docs/api-spec.yaml

Additional testing tools and integrations

Beyond the core testing approaches, these specific tool workflows can enhance your documentation validation process.

Tool-specific workflows

Postman integration:

# Generate collection from OpenAPI spec
curl http://localhost:8080/v3/api-docs.yaml > api-spec.yaml
# Import into Postman: File → Import → Upload api-spec.yaml
# Run collection tests to verify all endpoints

Swagger Editor workflow:

  1. Export specification: curl http://localhost:8080/v3/api-docs.yaml
  2. Import into https://editor.swagger.io/
  3. Validate structure and examples
  4. Generate client code for additional testing

Next steps