Skip to content

Commit c4b0302

Browse files
bmoyroudbmoyroud
authored
Add simulation specifications (#139)
* Lowercase summary * Update install command * Ignore .DS_Store * Add scaffold * Add api key parameter * Add request body * Fix parameters and add operation id * Add summary * Update api key parameter description * Add required, minItems and maxItems * Add Hex data type * Add Address data type * Add default for from, to, value and data fields * Add FromAddress and ToAddress data types (add descriptions) * Remove allOf * Use enum for method & add data types * Update TODOs * Add Polygon server url * Parameterise server url using network variable * Add format: password * Only show cURL, JS and Python snippets * Rename apiKey parameter * Remove scripts folder * Add TxObject data type * Add readOnly field * Add tags * Add package.json * Bump rdme version * Fix high severity vulnerability (npm audit fix) * Ignore .env file * Install dotenv and yaml packages * Add .env.template * Untrack .env.template * Update readme * Update readme * Remove .DS_Store * Add instructions to run scripts * Add id to spec * Add create and update scripts * Refactor parameters * Refactor schemas * Add known issue * Update paths * Refactor Transact specs * Update title and remove tags * Update readme * Add Id, JsonRpc, and Method data types * Move request body to eth_cancelPrivateTransaction * Fix paths * Move scripts using spawn to rdme folder * Add method name * Install axios and json-schema-ref-parser * Create Readme sdk (thin wrapper around subset of API methods) * Use Readme API instead of command line tool * Use oas-normalize to validate and dereference spec * Remove log * Fix overwritting spec (keep refs) * Add example spec (not to be uploaded) * Use Readme API instead of rdme in update script * Format spec * Add Spectral with default oas ruleset * Update paths * Add Spectral rule set * Add linting section to Readme * Bump severity of linting error * Fix ref path (now resolve properly) * Update readme id * Lint before creating / updating specs * Add function to debug Spectral * Update linting section * Add rdme for backwards compat (can scrap once we have ids) * Fix typo * Update instructions * Add links * Change sdk operation * Add alchemy_simulateExecution spec * Remove logging url (often invalid due to Readme API) * Add test networks * Update title, add test networks and add Readme id * Add example response * Remove whitespace * Add example response (flat) * Remove (optional) in description * Add required response fields * Add required response fields * Add asset and change types enums * Convert fields to camelCase * Add rule to check enum is macro cased * Remove data for Call, remove boolean value and fix typo * Remove use of Address in response enum * Update request field descriptions * Add descriptions * Fix descriptions & warn if none present * Add example for flat response * Add indentation * Remove value as required field * Mark id, json rpc and result as required response fields * Rename Result to FlatResult * Replace anyOf by oneOf * Revert back to anyOf * Add specs for bundle simulation * Add nested arrays * Fix number of items in array * Update description & fix bug * Fix issues
1 parent b7e00db commit c4b0302

29 files changed

+7225
-355
lines changed

‎.DS_Store

-6 KB
Binary file not shown.

‎.env.template

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
RDME_API_KEY=

‎.gitignore

+6-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,7 @@
1+
node_modules
2+
13
.github/
2-
node_modules
4+
5+
.DS_Store
6+
.env
7+
.env.template

‎.spectral.yaml

+197
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
extends: ["spectral:oas"]
2+
functions: [debug]
3+
rules:
4+
# OPEN API
5+
alchemy-version-3.1.0:
6+
severity: error
7+
description: "OpenAPI `openapi` must be set to version 3.1.0."
8+
given: $
9+
then:
10+
field: openapi
11+
function: pattern
12+
functionOptions:
13+
match: \b3.1.0\b
14+
15+
# INFO
16+
info-description: off
17+
info-contact: off
18+
19+
# SERVERS
20+
alchemy-servers-length:
21+
severity: error
22+
description: Servers must have 1 server object.
23+
given: $.servers
24+
then:
25+
function: length
26+
functionOptions:
27+
min: 1
28+
max: 1
29+
30+
alchemy-servers-url:
31+
severity: error
32+
description: Url must be valid format.
33+
given: $.servers.*
34+
then:
35+
field: url
36+
function: pattern
37+
functionOptions:
38+
match: "https://{network}.g.alchemy.com/v2"
39+
40+
alchemy-servers-networks-supported:
41+
severity: error
42+
description: "\"network\" property must be one of supported networks."
43+
given: $.servers[0].variables.network.enum.*
44+
then:
45+
- function: enumeration
46+
functionOptions:
47+
values:
48+
- eth-mainnet
49+
- eth-goerli
50+
- polygon-mainnet
51+
- polygon-mumbai
52+
- arb-mainnet
53+
- arb-goerli
54+
55+
alchemy-servers-network-casing:
56+
severity: error
57+
description: "\"network\" must be kebab cased and without digits."
58+
given: $.servers[0].variables.network.enum.*
59+
then:
60+
- function: casing
61+
functionOptions:
62+
type: kebab
63+
disallowDigits: true
64+
65+
alchemy-servers-networks-default:
66+
severity: error
67+
given: $.servers.0.variables.network.default
68+
description: Must have a default network.
69+
then:
70+
function: enumeration
71+
functionOptions:
72+
values:
73+
- eth-mainnet
74+
- polygon-mainnet
75+
- arb-mainnet
76+
77+
# X-README
78+
alchemy-x-readme-id:
79+
severity: warn
80+
given: $.x-readme
81+
message: "{{property}} missing. If creating a new spec, ignore this warning. If updating an existing one, id should be set."
82+
then:
83+
field: id
84+
function: defined
85+
86+
alchemy-x-readme-id-length:
87+
severity: warn
88+
given: $.x-readme
89+
description: "Id should have a length of 24."
90+
then:
91+
field: id
92+
function: length
93+
functionOptions:
94+
min: 24
95+
max: 24
96+
97+
# does not check for order or duplicates
98+
alchemy-x-readme-samples-languages:
99+
severity: warn
100+
given: $.x-readme.samples-languages.*
101+
description: "\"x-readme.samples-languages\" property must be one of [curl, javascript, python]"
102+
then:
103+
function: enumeration
104+
functionOptions:
105+
values:
106+
- curl
107+
- javascript
108+
- python
109+
110+
# PATHS
111+
alchemy-paths-json-rpc-1-path:
112+
severity: error
113+
given: $.paths
114+
description: "\"paths\" property must have exactly 1 path."
115+
then:
116+
function: length
117+
functionOptions:
118+
min: 1
119+
max: 1
120+
121+
alchemy-paths-json-rpc-path:
122+
severity: error
123+
description: "\"paths\" must have a property \"/{apiKey}\"."
124+
given: $.paths
125+
then:
126+
- field: "/{apiKey}"
127+
function: defined
128+
129+
# OPERATIONS
130+
operation-description: warn
131+
operation-tags: off
132+
133+
alchemy-operation-json-rpc-post:
134+
severity: error
135+
description: "\"/{apiKey}\" must just have property post."
136+
given: $.paths["/{apiKey}"]
137+
then:
138+
- function: length
139+
functionOptions:
140+
min: 1
141+
max: 1
142+
- field: post
143+
function: defined
144+
145+
alchemy-operation-summary:
146+
severity: error
147+
description: "Operation must have \"summary\""
148+
given: $.paths.*.*
149+
then:
150+
- field: summary
151+
function: defined
152+
153+
# already enforced via operation-operationId
154+
# alchemy-operation-operationId:
155+
# severity: error
156+
# description: "Operation must have \"operationId\""
157+
# given: $.paths.*.*
158+
# then:
159+
# - field: summary
160+
# function: defined
161+
162+
alchemy-operation-operationId-casing:
163+
severity: error
164+
message: "{{property}} must be kebab cased and without digits."
165+
given: $.paths.*.*
166+
then:
167+
- field: operationId
168+
function: casing
169+
functionOptions:
170+
type: kebab
171+
disallowDigits: true
172+
173+
# PARAMETERS
174+
alchemy-json-rpc-auth:
175+
severity: error
176+
description: "JSON RPC needs to use ApiKey parameter."
177+
given: $.paths.*.*.parameters[0]
178+
# very important to set to false so ref is not resolved
179+
resolved: false
180+
then:
181+
field: "$ref"
182+
function: "pattern"
183+
functionOptions:
184+
match: "../components/parameters.yaml#/ApiKey"
185+
186+
# ENUMS
187+
# TODO: this clashes with network enum above - fix this
188+
alchemy-enums-casing:
189+
severity: warn
190+
message: "Enums must be macro case (uppercase and separated by _)."
191+
given: $..enum.*
192+
then:
193+
function: casing
194+
functionOptions:
195+
type: macro
196+
197+
# TODO: add rule to check response fields are camelCased

‎README.md

+147-7
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,157 @@
1-
# docs-openapi-specs
1+
# Alchemy Docs
22

3-
OpenAPI Specs for methods on docs
3+
Hey there - thanks for checking our API docs! 👋
44

5-
## Installation
5+
This repo holds the OpenAPI specs that power our API Playgrounds at [docs.alchemy.com/reference](https://docs.alchemy.com/reference) ("Try it" sections on the right).
66

7-
Get the `rdme` dev dependency
7+
## Getting started
88

9+
1. Clone the repo.
10+
11+
```bash
12+
git clone https://github.com/alchemyplatform/docs-openapi-specs
913
```
10-
npm install
14+
15+
2. Install dev dependencies.
16+
17+
```bash
18+
npm i
1119
```
1220

13-
Run `rdme` commands by prefixing commands with `npx` to use the installed version
21+
## Frens
22+
23+
Feedback? Issues? Typos?
24+
25+
We are continously trying to improve our docs - any help is very welcomed! 😀
26+
27+
You can:
28+
29+
- suggest edits (top right of [Tutorials](https://docs.alchemy.com/docs) pages)
30+
- share feedback using 'Did this page help you? sections (bottom of [Tutorials](https://docs.alchemy.com/docs) / [API Reference](https://docs.alchemy.com/reference/api-overview) pages)
31+
- open issues [here](https://github.com/alchemyplatform/docs-openapi-specs/issues/new)
32+
33+
If you're feeling adventurous, feel free to open a pull request [here](https://github.com/alchemyplatform/docs-openapi-specs/compare).
34+
35+
> You currently can only modify API playgrounds. For pages or markdown edits in API Reference, please use one of the above options.
36+
37+
# WIP 👷‍♀️
38+
39+
> Below section is WIP.
40+
> Until we add ids to every spec, deploy specs as you normally would.
41+
42+
## Alchemists 👩‍🔬
43+
44+
To speed up your development, 2 commands are now available.
45+
46+
- `npm run create spec.yaml`
47+
- `npm run update spec.yaml`
48+
49+
You no longer need to run the `rdme` command line directly to push to staging.
50+
You also no longer need to pass an API key and readme id! 🎉
1451

52+
### First time?
53+
54+
> Make sure you first ran through the steps [above](#getting-started).
55+
56+
1. Clone `.env.template` into `.env`.
57+
58+
```bash
59+
cp .env.template .env
1560
```
16-
npx rdme <command>
61+
62+
2. Grab Readme API key.
63+
64+
3. Update `RDME_API_KEY` in `.env`.
65+
66+
### Creating new spec
67+
68+
> Known issue: will remove comments and format spec when run.
69+
70+
1. Write your spec (e.g. `newspec.yaml`).
71+
72+
2. Run `create` script passing the path to your spec.
73+
74+
```bash
75+
npm run create transact/newspec.yaml
1776
```
77+
78+
This will:
79+
80+
- deploy your spec to readme
81+
- create a page and id
82+
- associate page id with your spec
83+
84+
3. Your spec will be updated with a `x-readme.id` field. This is super important to ensure updates work smoothly in the future!
85+
86+
### Updating spec
87+
88+
Run `update` script. Ensure `x-readme.id` is set.
89+
90+
```bash
91+
npm run update spec.yml
92+
```
93+
94+
### Troubleshooting
95+
96+
1. Check `RDME_API_KEY` is set in `.env`.
97+
2. Check you provided a valid path to a `.yaml` file when running the scripts.
98+
99+
```bash
100+
npm run create spec.yaml
101+
npm run update spec.yaml
102+
```
103+
104+
3. Check the spec has a `x-readme.id` property. This id is used to match the spec on Readme's side.
105+
4. Reach out to Bastien if you have any issues running the scripts.
106+
107+
## Linting
108+
109+
Linting is ran automatically when using `npm run create` and `npm run update` (powered by [Spectral](https://github.com/stoplightio/spectral)).
110+
111+
You can run it manually using
112+
113+
```bash
114+
npx spectral lint spec.yaml
115+
```
116+
117+
Rules we currently adhere - [here](.spectral.yaml).
118+
119+
You should also install the extension for your editor.
120+
121+
- [JetBrains Plugin](https://plugins.jetbrains.com/plugin/18520-spectral)
122+
- [VS Code Spectral Extension](https://marketplace.visualstudio.com/items?itemName=stoplight.spectral)
123+
124+
### Quirks
125+
126+
We currently cannot use [`oas-normalize`](https://github.com/readmeio/oas-normalize) to resolve $refs in specs.
127+
128+
It relies on [`@readme/openapi-parser`](https://github.com/readmeio/openapi-parser) which relies on [`@readme/json-schema-ref-parser`](https://github.com/readmeio/json-schema-ref-parser).
129+
130+
`@readme/json-schema-ref-parser` is a fork of [`@apidevtools/json-schema-ref-parser`](https://github.com/APIDevTools/json-schema-ref-parser).
131+
132+
This is a known issue of `json-schema-ref-parser` - see [here](https://github.com/APIDevTools/json-schema-ref-parser/issues/200#issuecomment-1157687009).
133+
134+
Until the issue gets resolved and changes get merged upstream, solution is to dereference the spec using `@openapi-generator-plus/json-schema-ref-parser`(https://www.npmjs.com/package/@openapi-generator-plus/json-schema-ref-parser).
135+
136+
This also means validation is done prior to running scripts via Spectral rather than with `oas-normalize`.
137+
138+
## Future improvements
139+
140+
- Refactoring (OAS Components / Schemas, break up `nfts.yaml`, `sdk.yaml`).
141+
- More linting rules
142+
- update multiple specs at once
143+
- `create` and `update` scripts share a lot of code (can be simplified)
144+
- `create` script remove comments
145+
146+
## Resources
147+
148+
- [OpenAPI Specification v3.1.0](https://spec.openapis.org/oas/latest.html)
149+
150+
- [Readme - OpenAPI Compatibility Chart](https://docs.readme.com/main/docs/openapi-compatibility-chart)
151+
- [Readme - OpenAPI Extensions](https://docs.readme.com/main/docs/openapi-extensions)
152+
153+
- [Swagger.io - OpenAPI Guide](https://swagger.io/docs/specification/about/)
154+
- [Documenting APIs - OpenAPI tutorial](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step1_openapi_object.html)
155+
156+
- [Stoplight.io - Spectral](https://docs.stoplight.io/docs/spectral/674b27b261c3c-overview)
157+
- [JSONPath](https://goessner.net/articles/JsonPath/index.html)

‎components/parameters.yaml

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# once we move to header auth - we can move to securitySchemes instead of parameters
2+
ApiKey:
3+
name: apiKey
4+
in: path
5+
# TODO: should we link to /signup directly?
6+
description: For higher throughput, **[create your own API key](https://alchemy.com/?a=docs-demo)**.
7+
required: true
8+
schema:
9+
type: string
10+
# uncommenting below will hide API key but toggles password managers..
11+
# format: password
12+
default: docs-demo

0 commit comments

Comments
 (0)