{"id":21247116,"url":"https://github.com/alchemyplatform/docs-openapi-specs","last_synced_at":"2025-07-10T22:32:10.466Z","repository":{"id":37007690,"uuid":"500535162","full_name":"alchemyplatform/docs-openapi-specs","owner":"alchemyplatform","description":"OpenAPI Specs for methods on Alchemy docs ","archived":false,"fork":false,"pushed_at":"2024-10-24T01:33:21.000Z","size":9160,"stargazers_count":8,"open_issues_count":10,"forks_count":24,"subscribers_count":18,"default_branch":"main","last_synced_at":"2024-10-24T11:26:32.456Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alchemyplatform.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-06T17:44:35.000Z","updated_at":"2024-10-10T15:24:54.000Z","dependencies_parsed_at":"2023-02-19T14:45:51.063Z","dependency_job_id":"72bf7bb4-e186-4c0e-84f0-e8f5c9b5127d","html_url":"https://github.com/alchemyplatform/docs-openapi-specs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alchemyplatform%2Fdocs-openapi-specs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alchemyplatform%2Fdocs-openapi-specs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alchemyplatform%2Fdocs-openapi-specs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alchemyplatform%2Fdocs-openapi-specs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alchemyplatform","download_url":"https://codeload.github.com/alchemyplatform/docs-openapi-specs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225658502,"owners_count":17503667,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-21T02:16:01.753Z","updated_at":"2025-07-10T22:32:10.460Z","avatar_url":"https://github.com/alchemyplatform.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e \\[!WARNING]\n\u003e This repository is no longer maintained. Please visit our new documentation repository at \u003chttps://github.com/alchemyplatform/docs\u003e which holds all Alchemy OpenAPI specs.\n\n# Alchemy Docs\n\nHey there - thanks for checking our API docs! 👋\n\nThis 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).\n\n## Getting started\n\n1. Clone the repo.\n\n```bash\ngit clone https://github.com/alchemyplatform/docs-openapi-specs\n```\n\n2. Install dev dependencies.\n\n```bash\nnpm i\n```\n\n## Frens\n\nFeedback? Issues? Typos?\n\nWe are continuously trying to improve our docs - any help is very welcomed! 😀\n\nYou can:\n\n- suggest edits (top right of [Tutorials](https://docs.alchemy.com/docs) pages)\n- 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)\n- open issues [here](https://github.com/alchemyplatform/docs-openapi-specs/issues/new)\n\nIf you're feeling adventurous, feel free to open a pull request [here](https://github.com/alchemyplatform/docs-openapi-specs/compare).\n\n\u003e You currently can only modify API playgrounds. For pages or markdown edits in API Reference, please use one of the above options.\n\n# WIP 👷‍♀️\n\n\u003e Below section is WIP.\n\u003e Until we add ids to every spec, deploy specs as you normally would.\n\n## Alchemists 👩‍🔬\n\nTo speed up your development, 2 commands are now available.\n\n- `npm run create spec.yaml`\n- `npm run update spec.yaml`\n\nYou no longer need to run the `rdme` command line directly to push to staging.\nYou also no longer need to pass an API key and readme id! 🎉\n\n### First time?\n\n\u003e Make sure you first ran through the steps [above](#getting-started).\n\n1. Clone `.env.template` into `.env`.\n\n```bash\ncp .env.template .env\n```\n\n2. Grab Readme API key.\n\n3. Update `RDME_API_KEY` in `.env`.\n\n### Creating new spec\n\n\u003e Known issue: will remove comments and format spec when run.\n\n1. Write your spec (e.g. `newspec.yaml`).\n\n2. Run `create` script passing the path to your spec.\n\n```bash\n  npm run create transact/newspec.yaml\n```\n\nThis will:\n\n- deploy your spec to readme\n- create a page and id\n- associate page id with your spec\n\n3. Your spec will be updated with a `x-readme.id` field. This is super important to ensure updates work smoothly in the future!\n\n### Updating spec\n\nRun `update` script. Ensure `x-readme.id` is set.\n\n```bash\nnpm run update spec.yml\n```\n\n### Troubleshooting\n\n1. Check `RDME_API_KEY` is set in `.env`.\n2. Check you provided a valid path to a `.yaml` file when running the scripts.\n\n```bash\nnpm run create spec.yaml\nnpm run update spec.yaml\n```\n\n3. Check the spec has a `x-readme.id` property. This id is used to match the spec on Readme's side.\n4. Reach out to Bastien if you have any issues running the scripts.\n\n## Linting\n\nLinting is ran automatically when using `npm run create` and `npm run update` (powered by [Spectral](https://github.com/stoplightio/spectral)).\n\nYou can run it manually using\n\n```bash\nnpx spectral lint spec.yaml\n```\n\nRules we currently adhere - [here](.spectral.yaml).\n\nYou should also install the extension for your editor.\n\n- [JetBrains Plugin](https://plugins.jetbrains.com/plugin/18520-spectral)\n- [VS Code Spectral Extension](https://marketplace.visualstudio.com/items?itemName=stoplight.spectral)\n\n### Quirks\n\nWe currently cannot use [`oas-normalize`](https://github.com/readmeio/oas-normalize) to resolve $refs in specs.\n\nIt 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).\n\n`@readme/json-schema-ref-parser` is a fork of [`@apidevtools/json-schema-ref-parser`](https://github.com/APIDevTools/json-schema-ref-parser).\n\nThis is a known issue of `json-schema-ref-parser` - see [here](https://github.com/APIDevTools/json-schema-ref-parser/issues/200#issuecomment-1157687009).\n\nUntil 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).\n\nThis also means validation is done prior to running scripts via Spectral rather than with `oas-normalize`.\n\n## Future improvements\n\n- Refactoring (OAS Components / Schemas, break up `nfts.yaml`, `sdk.yaml`).\n- More linting rules\n- update multiple specs at once\n- `create` and `update` scripts share a lot of code (can be simplified)\n- `create` script remove comments\n\n## Resources\n\n- [OpenAPI Specification v3.1.0](https://spec.openapis.org/oas/latest.html)\n\n- [Readme - OpenAPI Compatibility Chart](https://docs.readme.com/main/docs/openapi-compatibility-chart)\n- [Readme - OpenAPI Extensions](https://docs.readme.com/main/docs/openapi-extensions)\n\n- [Swagger.io - OpenAPI Guide](https://swagger.io/docs/specification/about/)\n- [Documenting APIs - OpenAPI tutorial](https://idratherbewriting.com/learnapidoc/pubapis_openapi_step1_openapi_object.html)\n\n- [Stoplight.io - Spectral](https://docs.stoplight.io/docs/spectral/674b27b261c3c-overview)\n- [JSONPath](https://goessner.net/articles/JsonPath/index.html)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falchemyplatform%2Fdocs-openapi-specs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falchemyplatform%2Fdocs-openapi-specs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falchemyplatform%2Fdocs-openapi-specs/lists"}