Skip to content

README.md

Latest commit

 

History

History
99 lines (77 loc) · 4.42 KB

README.md

File metadata and controls

99 lines (77 loc) · 4.42 KB

StackQL Provider Utils

NPM Version GitHub Downloads (all assets, all releases)

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.

Table of Contents

Prerequisites

  • Node.js >= 20
  • npm or yarn
  • stackql for testing

Installation

Add @stackql/provider-utils to your package.json:

npm install @stackql/provider-utils
# or
yarn add @stackql/provider-utils

Directory Structure

A 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.

Provider Development Workflow

The library provides a streamlined workflow for creating StackQL providers from OpenAPI specifications:

  1. providerdev.split - Divide a large OpenAPI specification into smaller, service-specific files
  2. providerdev.normalize - Reshape split specs for relational consumption (flatten allOf, rename oneOf/anyOf, strip misplaced keywords, lower opaque objects)
  3. providerdev.analyze - Examine split API specifications to generate mapping recommendations
  4. providerdev.generate - Create StackQL provider extensions from specifications and mappings
  5. docgen.generateDocs - Generate comprehensive documentation for StackQL providers

Contributing

Contributions are welcome!

License

MIT

Support