A comprehensive toolkit for transforming OpenAPI specifications into StackQL providers. This library streamlines the process of parsing, mapping, validating, testing, and generating documentation for StackQL providers.
- Prerequisites
- Installation
- Directory Structure
- Provider Development Workflow
providerdev.split- Divide a large OpenAPI specification into smaller, service-specific filesproviderdev.analyze- Examine split API specifications to generate mapping recommendationsproviderdev.generate- Create StackQL provider extensions from specifications and mappingsdocgen.generateDocs- Generate comprehensive documentation for StackQL providers
- Contributing
- License
- Support
- Node.js >= 20
npmoryarnstackqlfor testing
Add @stackql/provider-utils to your package.json:
npm install @stackql/provider-utils
# or
yarn add @stackql/provider-utilsA typical project structure for the development of a stackql provider would be...
.
├── bin # convinience scripts
│ ├── ...
├── provider-dev
│ ├── config
│ │ └── all_services.csv # mappings generated or updated by the `providerdev.analyze` function, used by `providerdev.generate`
│ ├── docgen
│ │ └── provider-data # provider metadata used by `docgen.generateDocs`
│ │ ├── headerContent1.txt
│ │ └── headerContent2.txt
│ ├── downloaded # used to store the original spec for the provider
│ │ └── management-minimal.yaml
│ ├── openapi # output from `providerdev.generate`, this is the stackql provider
│ │ └── src
│ │ └── okta
│ │ └── v00.00.00000
│ │ ├── provider.yaml
│ │ └── services
│ │ ├── agentpools.yaml
│ │ ├── ...
│ ├── scripts # optional scripts for pre or post processing if required
│ │ └── post_processing.sh
│ └── source # output from `providerdev.split` if used, this is the source used with the mappings to generate the provider
│ ├── agentpools.yaml
│ ├── ...
└── website # docusaurus site
├── docs # output from `docgen.generateDocs`
│ ├── ...see stackql-provider-okta for a working example.
The library provides a streamlined workflow for creating StackQL providers from OpenAPI specifications:
providerdev.split- Divide a large OpenAPI specification into smaller, service-specific filesproviderdev.analyze- Examine split API specifications to generate mapping recommendationsproviderdev.generate- Create StackQL provider extensions from specifications and mappingsdocgen.generateDocs- Generate comprehensive documentation for StackQL providers
Contributions are welcome!
MIT