Eve library

Lilith Wisdom Platform API Documentation

Guide

Revision 1

On this page

This directory contains the Stoplight configuration and documentation for the Lilith Wisdom Platform API. It provides comprehensive API documentation with interactive examples, SDK integration guides, and automated validation.

πŸš€ Quick Start#

Prerequisites#

  • Node.js 16+ and npm 8+
  • Access to the Lilith API documentation

Installation#

bash
# Install dependencies
npm install

# Start local development server
npm run dev

# Build static documentation
npm run build

Development#

bash
# Start development server with hot reload
npm run dev

# Lint OpenAPI specification
npm run lint

# Fix linting issues automatically
npm run lint:fix

# Validate API documentation
npm run validate

πŸ“ Project Structure#

text
docs/stoplight/
β”œβ”€β”€ .spectral.yaml          # Spectral linting configuration
β”œβ”€β”€ stoplight.yaml          # Stoplight portal configuration
β”œβ”€β”€ package.json            # NPM package configuration
β”œβ”€β”€ README.md               # This file
β”œβ”€β”€ openapi.yaml            # OpenAPI specification (symlink)
β”œβ”€β”€ dist/                   # Built documentation output
β”œβ”€β”€ pages/                  # Custom documentation pages
β”‚   β”œβ”€β”€ getting-started.md
β”‚   β”œβ”€β”€ authentication.md
β”‚   └── guides/
β”œβ”€β”€ examples/               # Code examples and tutorials
β”‚   β”œβ”€β”€ typescript/
β”‚   β”œβ”€β”€ swift/
β”‚   └── kotlin/
β”œβ”€β”€ assets/                 # Static assets (images, logos)
└── styles/                 # Custom CSS styles
    └── custom.css

πŸ› οΈ Available Scripts#

Script Description
npm run dev Start local development server on port 3100
npm run build Build static documentation for deployment
npm run lint Lint OpenAPI specification with Spectral
npm run lint:fix Automatically fix linting issues
npm run validate Validate OpenAPI spec against custom rules
npm run test Run linting and validation
npm run preview Preview documentation locally
npm run docs:generate Generate documentation from OpenAPI
npm run docs:serve Serve documentation on port 3100
npm run clean Clean build artifacts and dependencies

πŸ”§ Configuration#

Spectral Configuration (.spectral.yaml)#

The .spectral.yaml file configures Spectral linting rules for OpenAPI validation:

  • OpenAPI Specification Rules: Ensures valid OpenAPI 3.1.0 syntax
  • Custom API Design Rules: Enforces consistent API design patterns
  • Security Rules: Validates authentication and authorization
  • Documentation Quality Rules: Ensures comprehensive documentation

Stoplight Configuration (stoplight.yaml)#

The stoplight.yaml file configures the API documentation portal:

  • Theme and Branding: Custom colors, logos, and typography
  • Navigation: Structured navigation with guides and references
  • SDK Documentation: Auto-generated SDK integration examples
  • Security Documentation: Authentication, rate limiting, and compliance
  • Deployment Configuration: Production deployment settings

πŸ“š Documentation Features#

Interactive API Reference#

  • Auto-generated from OpenAPI specification
  • Try-it-out functionality for all endpoints
  • Authentication examples with JWT tokens
  • Request/response examples
  • Error handling documentation

SDK Integration Guides#

Comprehensive guides for all official SDKs:

  • TypeScript/JavaScript: Web and Node.js applications
  • Swift: iOS and macOS applications
  • Kotlin: Android applications

Each guide includes:

  • Installation instructions
  • Authentication setup
  • Code examples
  • Best practices
  • Error handling

User Guides#

Step-by-step guides for common workflows:

  • Getting Started: Quick start guide
  • Authentication: Complete authentication flow
  • Chat Integration: Building chat features
  • Audio Streaming: Media content delivery
  • Push Notifications: Real-time notifications

Security Documentation#

  • Authentication: JWT token management
  • Rate Limiting: API usage limits
  • Data Protection: Encryption and compliance
  • Best Practices: Security recommendations

πŸš€ Deployment#

Local Development#

bash
# Start development server
npm run dev

# Open in browser
open http://localhost:3100

Staging Deployment#

bash
# Build and deploy to staging
npm run deploy:staging

Production Deployment#

bash
# Build and deploy to production
npm run deploy:production

CI/CD Integration#

The documentation is automatically built and deployed via GitHub Actions:

  • On Push: Build and validate documentation
  • On Pull Request: Build staging version
  • On Main: Deploy to production

πŸ” Validation and Quality#

Automated Checks#

  • OpenAPI Validation: Ensures valid API specification
  • Documentation Quality: Validates descriptions and examples
  • Link Validation: Checks all internal and external links
  • Code Examples: Validates all code snippets

Quality Gates#

The documentation must pass all quality gates before deployment:

  1. βœ… Spectral Linting: No linting errors
  2. βœ… OpenAPI Validation: Valid specification
  3. βœ… Content Validation: All descriptions present
  4. βœ… Example Testing: All code examples work
  5. βœ… Link Checking: No broken links

🎨 Customization#

Theme Customization#

Edit stoplight.yaml to customize:

  • Colors: Primary, secondary, accent colors
  • Typography: Font families and sizes
  • Logo: Custom logo and favicon
  • Layout: Navigation and page structure

Custom Pages#

Add custom markdown pages in the pages/ directory:

  1. Create .md file with frontmatter
  2. Add to navigation in stoplight.yaml
  3. Include in build process

Custom Styles#

Add custom CSS in styles/custom.css:

css
/* Custom styles for Lilith branding */
.api-docs {
  --primary-color: #6366f1;
  --secondary-color: #8b5cf6;
  --accent-color: #ec4899;
}

πŸ“Š Monitoring and Analytics#

Performance Monitoring#

  • Page Load Times: Core Web Vitals tracking
  • API Response Times: Documentation API performance
  • User Analytics: Google Analytics integration
  • Error Tracking: Sentry error monitoring

Usage Analytics#

  • Page Views: Most popular documentation pages
  • Search Queries: Common user searches
  • SDK Downloads: Package download statistics
  • API Usage: Endpoint usage patterns

🀝 Contributing#

Adding New API Documentation#

  1. Update OpenAPI spec in ../../openapi/openapi.yaml
  2. Add examples in appropriate SDK directories
  3. Update guides if new features are added
  4. Run validation with npm run test
  5. Submit pull request

Documentation Style Guide#

  • Clear descriptions: Use simple, clear language
  • Code examples: Provide working examples for all SDKs
  • Error handling: Document common errors and solutions
  • Version compatibility: Note version requirements

Review Process#

All documentation changes require:

  1. Automated validation: Pass all quality gates
  2. Manual review: Technical accuracy review
  3. User testing: Validate user experience
  4. Approval: Documentation team approval

πŸ†˜ Support#

Getting Help#

  • Documentation: https://docs.lilith.ai
  • API Support: api-support@lilith.ai
  • GitHub Issues: https://github.com/lilith-ai/lilith-platform/issues
  • Community: https://community.lilith.ai

Common Issues#

Build Errors:

  • Check Node.js version (16+ required)
  • Run npm install to update dependencies
  • Clear cache with npm run clean

Linting Errors:

  • Run npm run lint:fix to auto-fix issues
  • Check .spectral.yaml for rule definitions
  • Update OpenAPI spec if validation fails

Deployment Issues:

  • Verify AWS credentials for deployment
  • Check build output in dist/ directory
  • Review CI/CD logs for errors

πŸ“„ License#

This documentation is licensed under the MIT License. See LICENSE file for details.

  • Lilith Platform: https://lilith.ai
  • API Portal: https://portal.lilith.ai
  • Status Page: https://status.lilith.ai
  • Developer Blog: https://blog.lilith.ai
  • GitHub Repository: https://github.com/lilith-ai/lilith-platform

Generated with ❀️ by the Lilith Platform Team