Skip to content

docs-generation-guide.md

Latest commit

 

History

History
320 lines (244 loc) · 10 KB

docs-generation-guide.md

File metadata and controls

320 lines (244 loc) · 10 KB

Documentation Generation Guide

This guide explains how to use the generate-docs.sh script to create a complete, standalone documentation website for the Customer Management API.

Overview

The generate-docs.sh script creates a self-contained documentation website that includes:

  • Interactive API Documentation (Swagger UI)
  • Landing Page with navigation
  • Technical Writing Guides converted from Markdown to HTML
  • Postman Collections and testing resources
  • Custom Styling and responsive design

Prerequisites

Required

  • Bash shell (macOS, Linux, or WSL on Windows)
  • curl (for downloading Swagger UI)
  • sed (for text processing)

Optional but Recommended

Note: Without pandoc, the script will copy Markdown files as-is instead of converting them to HTML.

How to Use

Step 1: Make the Script Executable

chmod +x generate-docs.sh

Step 2: Run the Generation Script

./generate-docs.sh

Step 3: Start the Documentation Server

Important: The generated documentation must be served via HTTP (not opened as files) because Swagger UI needs to fetch the OpenAPI specification via AJAX, which browsers block with file:// protocol.

Start the Server

cd docs-site
python3 -m http.server 8081

Stop the Server

Press Ctrl+C in the terminal where the server is running, or if you need to kill it from another terminal:

# Find the process ID
lsof -i :8081

# Kill the process (replace PID with the actual process ID from above)
kill <PID>

Step 4: Access Your Documentation

What Gets Generated

The script creates a docs-site/ directory with the following structure:

docs-site/
├── index.html                           # Swagger UI (Interactive API)
├── landing.html                         # Professional homepage
├── customer-api.yaml                    # OpenAPI specification
├── swagger-ui*.js/css                   # Swagger UI assets
├── style.css                           # Custom styling for documentation
├── navigation.html                     # Navigation component
├── tech-writer-reference/              # Converted documentation
│   ├── TECH_WRITER_GUIDE.html
│   ├── 01-generated-documentation-guide.html
│   ├── 02-manual-yaml-writing-guide.html
│   ├── 03-testing-validation-guide.html
│   ├── 04-api-documentation-publishing-guide.html
│   └── reference/                      # Reference materials
│       ├── openapi-examples.html
│       ├── annotation-reference.html
│       └── tools-comparison.html
└── api-assets/                         # Testing resources
    ├── postman/                        # Postman collections
    └── openapi/                        # OpenAPI examples

Detailed Process Breakdown

Phase 1: Setup and Download

  1. Creates output directory (docs-site/)
  2. Downloads Swagger UI from GitHub (latest master)
  3. Extracts Swagger UI assets to the docs-site directory

Phase 2: API Configuration

  1. Copies OpenAPI specification from docs/tech-writer-reference/api-assets/openapi/customer-api.yaml
  2. Configures Swagger UI to load your API instead of the petstore demo
  3. Updates swagger-initializer.js with the correct API path

Phase 3: Documentation Conversion

  1. Detects pandoc availability
  2. If pandoc is available:
    • Removes Jekyll front matter from Markdown files
    • Extracts first heading as HTML title
    • Removes duplicate headings from content
    • Converts Markdown to styled HTML with custom CSS
  3. If pandoc is not available:
    • Copies Markdown files as-is

Phase 4: Asset Organization

  1. Copies custom landing page from docs-template/index.html
  2. Creates directory structure for assets
  3. Copies Postman collections and OpenAPI examples
  4. Generates navigation components

Phase 5: Styling and Polish

  1. Creates custom CSS for converted documentation
  2. Applies consistent styling across all pages
  3. Ensures responsive design for mobile compatibility

Common Issues and Solutions

Issue: "Fetch error" in Swagger UI

Symptom: Swagger UI shows "NetworkError when attempting to fetch resource" Cause: Opening files with file:// protocol instead of HTTP Solution: Start the Python HTTP server as described in Step 3

Issue: Duplicate titles on documentation pages

Symptom: Pages show the same title twice Cause: Both Jekyll front matter and first heading being processed Solution: The script now automatically handles this by extracting and removing duplicate headings

Issue: "Explore API" button returns 404

Symptom: Landing page link to Swagger UI doesn't work Cause: Incorrect path in landing page template Solution: The script now correctly links to index.html

Issue: Swagger UI loads petstore demo instead of your API

Symptom: Interactive documentation shows petstore API Cause: Swagger UI configuration not updated Solution: The script now properly configures swagger-initializer.js

Advanced Usage

Custom API Specification

To use a different OpenAPI specification:

  1. Replace docs/tech-writer-reference/api-assets/openapi/customer-api.yaml
  2. Run ./generate-docs.sh

Custom Landing Page

To customize the landing page:

  1. Edit docs-template/index.html
  2. Run ./generate-docs.sh

Adding Additional Documentation

To add new documentation files:

  1. Add Markdown files to appropriate directories under docs/
  2. Update the script to include them in the conversion process
  3. Run ./generate-docs.sh

Deployment Options

The generated docs-site/ folder is completely self-contained and can be deployed to:

Static Hosting Services

  • GitHub Pages: Push to repository, enable Pages
  • Netlify: Drag and drop docs-site/ folder
  • Vercel: Deploy via CLI or web interface
  • AWS S3: Upload and enable static website hosting

Traditional Web Servers

  • Apache: Copy to document root
  • Nginx: Copy to web directory
  • Any HTTP server: The folder contains only static files

Example GitHub Pages Deployment

# Create a new branch for GitHub Pages
git checkout -b gh-pages
git add docs-site/
git commit -m "Add generated documentation"
git push origin gh-pages

# Enable GitHub Pages in repository settings
# Point to gh-pages branch, docs-site/ folder

Regeneration Workflow

When you update your documentation or API:

  1. Make changes to source files (Markdown docs, OpenAPI spec)
  2. Regenerate documentation: 
    rm -rf docs-site
./generate-docs.sh
  3. Test locally: 
    cd docs-site
python3 -m http.server 8081
# Visit http://localhost:8081/landing.html
# Stop with Ctrl+C when done
  4. Deploy updated files to your hosting platform

Script Customization

The generate-docs.sh script can be customized by modifying these sections:

Change Output Directory

# Line 9: Change output directory name
mkdir -p my-custom-docs
cd my-custom-docs

Add Custom CSS

# Around line 60: Modify the CSS section
cat > style.css << 'EOF'
/* Your custom CSS here */

Include Additional Files

# Around line 36: Add more pandoc conversion commands
convert_md_to_html "../path/to/your/file.md" "output/path.html" "../style.css"

Troubleshooting

Script Fails to Download Swagger UI

Check internet connection and try again:

curl -L https://github.com/swagger-api/swagger-ui/archive/master.zip

Pandoc Not Found

Install pandoc or run without it:

  • The script works without pandoc but copies Markdown files instead of converting to HTML
  • Install pandoc for better HTML output with styling

Permission Denied

Make script executable:

chmod +x generate-docs.sh

Port 8081 Already in Use

Check what's using the port and kill it:

# Find what's using port 8081
lsof -i :8081

# Kill the process (replace PID with the actual process ID)
kill <PID>

# Then start the server normally
python3 -m http.server 8081

Or use a different port:

python3 -m http.server 8082
# Then visit http://localhost:8082/landing.html

Integration with Spring Boot

If you have the Spring Boot application running (./mvnw spring-boot:run):

  1. API runs on: http://localhost:8080
  2. Documentation runs on: http://localhost:8081
  3. Test endpoints directly from Swagger UI by clicking "Try it out"

The Swagger UI will make requests to your running API, allowing full integration testing.

Performance Notes

Generation Speed

  • With pandoc: ~10-15 seconds (includes Markdown conversion)
  • Without pandoc: ~5-8 seconds (copies files only)
  • Swagger UI download: ~2-5 seconds (cached after first run)

Output Size

  • Complete site: ~2-3 MB
  • Swagger UI assets: ~1.7 MB
  • Documentation: ~300-500 KB
  • Custom assets: ~100-200 KB

Security Considerations

Local Development

  • The HTTP server is only accessible from your machine
  • No authentication or security headers needed for local use

Production Deployment

  • Consider adding HTTPS
  • Implement proper security headers
  • Use CDN for better performance
  • Add authentication if documentation is private

Conclusion

The generate-docs.sh script provides a complete solution for creating professional, interactive API documentation. It combines the power of Swagger UI for API testing with beautifully formatted technical documentation, all in a self-contained package ready for deployment anywhere.

For questions or issues, refer to the troubleshooting section or check the script source code for detailed implementation.
⚡