53 lines
1.6 KiB
Markdown
53 lines
1.6 KiB
Markdown
|
# alpaca-oas
|
||
|
|
|
||
|
|
Alpaca [OpenAPI specifcations (OAS)](https://swagger.io/docs/specification/about/).
|
||
|
|
|
||
|
|
---
|
||
|
|
# ⚠️ These specs are still a work in progress and might not at this time accurately reflect the latest state of our apis. ⚠️
|
||
|
|
|
||
|
|
We are currently working on making these specs accurate but currently some inaccuracies or missing endpoints are expected.
|
||
|
|
|
||
|
|
---
|
||
|
|
## Getting started
|
||
|
|
|
||
|
|
Install packages / tools for working with the OAS project
|
||
|
|
|
||
|
|
```
|
||
|
|
npm i
|
||
|
|
```
|
||
|
|
|
||
|
|
## Validate an OpenAPI spec
|
||
|
|
|
||
|
|
`npm run validate broker/openapi.yaml`
|
||
|
|
|
||
|
|
You can also optionally run the `./scripts/validate-all.sh` to validate all the spec files
|
||
|
|
|
||
|
|
## Lint an OpenAPI spec
|
||
|
|
|
||
|
|
`npm run lint broker/openapi.yaml`
|
||
|
|
|
||
|
|
You can also optionally run the `./scripts/lint-all.sh` to lint all the spec files
|
||
|
|
|
||
|
|
## Serve an OpenAPI doc preview
|
||
|
|
|
||
|
|
`npm run serve broker/openapi.yaml --options.onlyRequiredInSamples`
|
||
|
|
|
||
|
|
## Generate API clients for a given language
|
||
|
|
|
||
|
|
View list of potential generators: `npx openapi-generator-cli list`
|
||
|
|
|
||
|
|
Below example generates packages for Java and R from Broker API OpenAPI spec.
|
||
|
|
|
||
|
|
```
|
||
|
|
npx openapi-generator-cli generate -i broker/openapi.yaml -g java -o build/java
|
||
|
|
npx openapi-generator-cli generate -i broker/openapi.yaml -g r -o build/r
|
||
|
|
```
|
||
|
|
|
||
|
|
While we include this in our dependencies, documenting how to use openapi-generator-cli is a bit out of scope for this document,
|
||
|
|
please see [their github page](https://github.com/OpenAPITools/openapi-generator-cli) for more information on how to use it.
|
||
|
|
|
||
|
|
|
||
|
|
## Generate Postman Collection
|
||
|
|
|
||
|
|
`npx openapi2postmanv2 -s broker/openapi.yaml -o build/collection.json -p -O folderStrategy=paths,includeAuthInfoInExample=true`
|