DataDog MCP Server

# Spectral OpenAPI Linting This document explains how to use Spectral for linting OpenAPI specifications in the DataDog MCP project. ## Overview Spectral is a powerful open-source linter that can enforce custom validation rules across OpenAPI YAML files, helping detect: - Unused parameters, components, and responses - Missing descriptions and examples - Deprecated features - Security issues - API design best practices ## Installation Spectral is automatically installed as part of the development tools: ```bash # Install all development tools (includes Spectral) make install-dev-tools # Or install Spectral specifically make install-spectral ``` ## Available Make Targets ### Lint Commands ```bash # Lint both v1 and v2 OpenAPI specifications make lint-openapi # Lint only DataDog API v1 specification make lint-openapi-v1 # Lint only DataDog API v2 specification make lint-openapi-v2 # Lint a specific OpenAPI file make lint-openapi-file FILE=path/to/your/openapi.yaml ``` ### Installation ```bash # Install Spectral CLI tool make install-spectral # Install all development tools (includes Spectral) make install-dev-tools ``` ## Configuration The Spectral configuration is defined in `.spectral.yml` and includes: ### Default Rules - **operation-operationId**: Error if operations lack operationId - **operation-description**: Warning if operations lack descriptions - **operation-summary**: Warning if operations lack summaries - **operation-tags**: Warning if operations lack tags - **schema-description**: Warning if schemas lack descriptions - **response-description**: Warning if responses lack descriptions - **security-defined**: Error if security schemes are not defined - **path-params**: Error if path parameters are not declared ### Custom Rules for DataDog APIs - **info-contact**: Warning if API contact information is missing - **info-license**: Warning if API license information is missing - **info-description**: Warning if API description is missing - **components-schemas**: Warning for schema component issues - **components-responses**: Warning for response component issues - **components-parameters**: Warning for parameter component issues ### Ignored Files The configuration ignores: - Split OpenAPI files (`schemas/*/split/**`) - Node modules (`**/node_modules/**`) - Git files (`**/.git/**`) ## Usage Examples ### Basic Linting ```bash # Lint all OpenAPI specifications make lint-openapi ``` ### Lint Specific Files ```bash # Lint a specific OpenAPI file make lint-openapi-file FILE=schemas/v1/openapi.yaml # Lint a custom file make lint-openapi-file FILE=my-custom-api.yaml ``` ### Direct Spectral Usage ```bash # Lint with default rules spectral lint schemas/v1/openapi.yaml # Lint with custom ruleset spectral lint schemas/v1/openapi.yaml --ruleset .spectral.yml # Lint with specific format spectral lint schemas/v1/openapi.yaml --format json # Lint with verbose output spectral lint schemas/v1/openapi.yaml --verbose ``` ## Configuration Customization ### Adding Custom Rules To add custom rules, edit `.spectral.yml`: ```yaml rules: # Your custom rules my-custom-rule: warn another-rule: error ``` ### Custom Functions For complex validation logic, you can create custom functions in `spectral-functions.js`: ```javascript module.exports = { 'my-custom-function': function(targetVal, options, { path }) { // Your validation logic return []; } }; ``` ### Rule Severity Levels - **error**: Causes linting to fail - **warn**: Shows warning but doesn't fail - **info**: Informational message - **hint**: Suggestion for improvement ## Common Issues and Solutions ### Missing Operation Descriptions ```yaml # ❌ Bad paths: /api/v1/users: get: summary: Get users # ✅ Good paths: /api/v1/users: get: summary: Get users description: Retrieve a list of all users in the system ``` ### Missing Schema Descriptions ```yaml # ❌ Bad components: schemas: User: type: object properties: id: type: integer # ✅ Good components: schemas: User: type: object description: A user in the system properties: id: type: integer description: Unique identifier for the user ``` ### Unused Components Spectral can detect unused components: ```yaml # This schema is defined but never referenced components: schemas: UnusedSchema: type: object ``` ## Integration with CI/CD ### Pre-commit Hooks Add Spectral linting to pre-commit hooks: ```yaml # .pre-commit-config.yaml repos: - repo: local hooks: - id: spectral-lint name: Spectral OpenAPI Linting entry: make lint-openapi language: system files: \.ya?ml$ ``` ### GitHub Actions ```yaml # .github/workflows/lint-openapi.yml name: Lint OpenAPI on: [push, pull_request] jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Setup Node.js uses: actions/setup-node@v2 with: node-version: '18' - name: Install dependencies run: make install-dev-tools - name: Lint OpenAPI run: make lint-openapi ``` ## Advanced Usage ### Custom Rulesets Create multiple rulesets for different purposes: ```yaml # .spectral-strict.yml extends: [".spectral.yml"] rules: operation-description: error # Make warnings into errors schema-description: error ``` ### Excluding Rules ```yaml rules: operation-description: off # Disable specific rules ``` ### File-specific Rules ```yaml rules: operation-description: - warn - except: - "schemas/v1/openapi.yaml" # Skip for v1 API ``` ## Best Practices 1. **Start with Warnings**: Begin with warning-level rules and gradually increase severity 2. **Regular Linting**: Run linting regularly during development 3. **Custom Rules**: Add custom rules specific to your API design standards 4. **Documentation**: Document any custom rules and their purpose 5. **Team Alignment**: Ensure the team understands and follows the linting rules ## Troubleshooting ### Common Errors 1. **Module Not Found**: Ensure Spectral is properly installed 2. **Configuration Errors**: Check YAML syntax in `.spectral.yml` 3. **File Not Found**: Verify file paths are correct 4. **Permission Issues**: Ensure proper file permissions 5. **Sandboxing Issues**: Some systems may have sandboxing restrictions that prevent Spectral from running ### Debug Mode ```bash # Run with verbose output for debugging spectral lint schemas/v1/openapi.yaml --verbose ``` ### Configuration Validation ```bash # Validate your Spectral configuration spectral lint --ruleset .spectral.yml --help ``` ### Alternative Approaches If Spectral encounters system-level issues, consider these alternatives: 1. **Use Online Tools**: - [Spectral Online](https://stoplight.io/open-source/spectral) for web-based linting - [Swagger Editor](https://editor.swagger.io/) for validation 2. **CI/CD Integration**: Run Spectral in CI/CD environments where system restrictions are typically less strict ### System Compatibility Spectral requires Node.js and may not work in all environments due to: - System sandboxing restrictions - Node.js version compatibility - File system permissions - Security policies The configuration files are still valid and can be used in compatible environments. ## Related Documentation - [OpenAPI Splitting Guide](openapi-splitting.md) - How to split large OpenAPI specifications - [Available Tools](tools.md) - Complete list of implementable DataDog tools - [Test Documentation](tests.md) - Test coverage and implementation details - [README](../README.md) - Project overview and quick start guide ## Resources - [Spectral Documentation](https://meta.stoplight.io/docs/spectral/) - [OpenAPI Specification](https://swagger.io/specification/) - [Spectral Rules Reference](https://meta.stoplight.io/docs/spectral/docs/reference/rules.md)