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#
# Install dependencies
npm install
# Start local development server
npm run dev
# Build static documentation
npm run build
Development#
# 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#
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#
# Start development server
npm run dev
# Open in browser
open http://localhost:3100
Staging Deployment#
# Build and deploy to staging
npm run deploy:staging
Production Deployment#
# 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:
- β Spectral Linting: No linting errors
- β OpenAPI Validation: Valid specification
- β Content Validation: All descriptions present
- β Example Testing: All code examples work
- β 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:
- Create
.mdfile with frontmatter - Add to navigation in
stoplight.yaml - Include in build process
Custom Styles#
Add custom CSS in styles/custom.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#
- Update OpenAPI spec in
../../openapi/openapi.yaml - Add examples in appropriate SDK directories
- Update guides if new features are added
- Run validation with
npm run test - 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:
- Automated validation: Pass all quality gates
- Manual review: Technical accuracy review
- User testing: Validate user experience
- 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 installto update dependencies - Clear cache with
npm run clean
Linting Errors:
- Run
npm run lint:fixto auto-fix issues - Check
.spectral.yamlfor 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.
π Related Links#
- 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