Skip to content

README.md

Latest commit

 

History

History
309 lines (232 loc) · 8.21 KB

README.md

File metadata and controls

309 lines (232 loc) · 8.21 KB

Bookstore API Documentation

A comprehensive, interactive API documentation site built with Swagger UI that showcases a complete RESTful bookstore management system. Features dynamic YAML loading, modern responsive design, and easy deployment to any static hosting platform.

Live Demo

  • GitHub Repository: https://github.com/alokbash/swagger-openapi-sample

API Overview

The Bookstore API provides a complete solution for managing an online bookstore.

Project Structure

swagger-openapi-sample/
├── index.html          # Main Swagger UI page with dynamic YAML loading
├── openapi.yaml        # Your OpenAPI 3.x specification
├── package.json        # Project metadata and scripts
├── .gitignore          # Git ignore patterns
└── README.md           # This file

Local Development

Prerequisites

  • Node.js 16+ (for development tools)
  • A modern web browser
  • Git

Quick Start

  1. Clone the repository:

    git clone https://github.com/alokbash/swagger-openapi-sample.git
cd swagger-openapi-sample

  2. Install development dependencies (optional):

    npm install

  3. Start local development server:

    npm run dev

    Or serve manually:

    # Using Python
python -m http.server 3000

# Using Node.js http-server
npx http-server . -p 3000 -c-1 --cors

# Using PHP
php -S localhost:3000

  4. Open your browser to http://localhost:3000

Available Scripts

npm run start      # Start development server on port 3000
npm run dev        # Start development server and open browser
npm run validate   # Validate OpenAPI specification syntax and structure
npm run lint       # Lint YAML syntax and formatting

Testing the API Documentation

  1. Start the development server:

    npm run dev

  2. Open your browser to http://localhost:3000

  3. Explore the API:

    • Browse the different endpoint categories (Books, Orders, Users)
    • Try out the interactive examples
    • Test authentication flows
    • Examine request/response schemas

Endpoints Overview

Books API

  • GET /books - List books with filtering, sorting, and pagination
  • GET /books/{bookId} - Get detailed book information
  • POST /books - Create new book (admin only)

Orders API

  • GET /orders - List user's orders with status filtering
  • POST /orders - Create new order with items and shipping
  • GET /orders/{orderId} - Get specific order details

Users API

  • POST /users/register - Register new user account
  • POST /users/login - Authenticate and get JWT token
  • GET /users/profile - Get user profile information

Editing Your API Specification

  1. Edit the OpenAPI spec: Modify openapi.yaml with your API endpoints, schemas, and documentation
  2. Validate your changes: Run npm run validate to ensure valid OpenAPI format
  3. Test locally: The page will automatically reload and display your changes
  4. Use Swagger Editor: Visit editor.swagger.io for visual editing

Deployment

This is a static site that can be deployed to any hosting platform:

Static Hosting Platforms

  • GitHub Pages: Enable Pages in repository settings
  • Vercel: Connect your GitHub repository
  • Netlify: Drag and drop or connect via Git
  • Any web server: Upload files to your server

Deployment Steps

  1. Push to GitHub:

    git add .
git commit -m "Ready for deployment"
git push origin main

  2. Deploy to your preferred platform:

    • Most platforms will automatically detect this as a static site
    • No build step required - just serve the files
    • Ensure your hosting platform serves YAML files with correct MIME type

Customization

Styling Customization

Edit the <style> section in index.html to customize:

/* Brand colors */
:root {
  --primary-color: #3498db;
  --secondary-color: #2ecc71;
  --accent-color: #e74c3c;
}

/* Custom styling examples */
.swagger-ui .info .title {
  color: var(--primary-color);
  font-family: 'Your Brand Font', sans-serif;
}

Swagger UI Configuration

Modify the SwaggerUIBundle configuration in index.html:

SwaggerUIBundle({
  spec: spec,
  dom_id: '#swagger-ui',
  deepLinking: true,
  tryItOutEnabled: true,
  
  // Customization options
  defaultModelsExpandDepth: 2,     // How deep to expand models
  docExpansion: 'list',            // 'list', 'full', or 'none'
  filter: true,                    // Enable search/filter
  showExtensions: true,            // Show vendor extensions
  showCommonExtensions: true,      // Show common extensions
  
  // Theme and layout
  layout: "BaseLayout",
  
  // Request interceptor for authentication
  requestInterceptor: (request) => {
    const token = localStorage.getItem('authToken');
    if (token) {
      request.headers.Authorization = `Bearer ${token}`;
    }
    return request;
  }
});

Multiple API Specifications

To support multiple API versions or services:

  1. Create additional YAML files:

    openapi-v1.yaml    # Version 1 API
openapi-v2.yaml    # Version 2 API
admin-api.yaml     # Admin API

  2. Add version switching:

    // Get version from URL parameter
const urlParams = new URLSearchParams(window.location.search);
const version = urlParams.get('version') || 'v1';
const specUrl = `./openapi-${version}.yaml`;

  3. Update navigation:

    <div class="api-version-selector">
  <a href="?version=v1">API v1</a>
  <a href="?version=v2">API v2</a>
  <a href="?version=admin">Admin API</a>
</div>

Custom Branding

Add your company branding:

<!-- Add to index.html head -->
<link rel="icon" href="./favicon.ico">
<meta property="og:title" content="Your Company API Documentation">
<meta property="og:description" content="Comprehensive API documentation">
<meta property="og:image" content="./api-preview.png">

Troubleshooting

Common Issues & Solutions

"Error Loading API Documentation"

Symptoms: Error page appears instead of API documentation

Solutions:

  • ✅ Ensure openapi.yaml exists in the project root
  • ✅ Validate YAML syntax: npm run lint
  • ✅ Check browser console for detailed errors (F12)
  • ✅ Verify file is accessible via HTTP (not file:// protocol)
  • ✅ Test with a simple HTTP server: npm run start

CORS Issues in Local Development

Symptoms: "Access blocked by CORS policy" errors

Solutions:

  • ✅ Always use an HTTP server (not file:// protocol)
  • ✅ Use provided npm scripts: npm run dev
  • ✅ For custom servers, enable CORS headers
  • ✅ Check that YAML file is served with correct MIME type

Deployment Issues

Symptoms: Site doesn't deploy or shows errors

Solutions:

  • ✅ Check deployment logs in your hosting platform's dashboard
  • ✅ Ensure all files are committed to Git: git status
  • ✅ Verify YAML files are served with correct MIME type
  • ✅ Check routing configuration for your hosting platform
  • ✅ Validate OpenAPI spec before deployment: npm run validate

Swagger UI Layout Issues

Symptoms: "No layout defined" errors

Solutions:

  • ✅ Use correct layout names: "BaseLayout" or "StandaloneLayout"
  • ✅ Check Swagger UI version compatibility
  • ✅ Verify CDN links are accessible

Mobile Display Issues

Symptoms: Poor mobile experience

Solutions:

  • ✅ Ensure viewport meta tag is present
  • ✅ Test responsive design with browser dev tools
  • ✅ Check CSS media queries in custom styles

Debugging Steps

  1. Check Browser Console (F12):

    Look for JavaScript errors, network failures, or CORS issues

  2. Validate OpenAPI Spec:

    npm run validate
npm run lint

  3. Test Local Server:

    npm run start
# Then visit http://localhost:3000

  4. Check Network Tab:

    Verify openapi.yaml loads successfully (200 status)
Check response headers and content type

Getting Help