open-rpc / playground

A place to play around with OpenRPC. https://playground.open-rpc.org

OpenRPC Playground

This is a tool for editing, validating and previewing OpenRPC documents.

What is it?

This is meant to be an all-in-one developer portal for OpenRPC documents. It includes an editor and a live-preview of the documentation.

This helps developers visualize the OpenRPC and iterate very quickly on creating OpenRPC documents via the built in editor tooling.

Usage

Navigate to playground.open-rpc.org and start playing around. You can build your own OpenRPC document, validate existing documents quickly, or use the examples.

Keybinds

• CTRL + SPACE - auto complete (TAB or ENTER to complete)
• CTRL + N/CTRL + P - down/up a line (also works as up/down in autocomplete)
• ALT + SHIFT + F - format document

Chords

• CMD + K + BACKSPACE - reset to empty schema
• CMD + K + I - pop up tooltip under cursor
• CMD + K + V - toggle vim mode
• CMD + K + R - replace meta schema

Configuration via Query String Parameters

The query string parameters can be used to configure the playground in different ways.

uiSchema

uiSchema is used for UI layer configuration. here is its interface:

schemaUrl

schemaUrl - fetch schema by URL and display it as the content of the playground on startup.

schema

schema - JSON String used to display it as the content of the playground on startup.

examples:

• set splitView to false
  • http://playground.open-rpc.org/?uiSchema[appBar][ui:splitView]=false
• hide appbar input bar
  • http://playground.open-rpc.org/?uiSchema[appBar][ui:input]=false
• hide appbar examples dropdown
  • http://playground.open-rpc.org/?uiSchema[appBar][ui:examplesDropdown]=false
• provide custom name and logo
• http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=My Site&uiSchema[appBar][ui:logoUrl]=https://github.com/open-rpc/design/raw/master/icons/open-rpc-logo-noText/open-rpc-logo-noText%20(PNG)/128x128.png

Pro tip

If you want to use the content of a Github Gist with the playground, you can:

• use the latest revision for a Gist file

https://playground.open-rpc.org/?schemaUrl=https://gist.githubusercontent.com/[gist username]/[gist ID]/raw/[file name]

• use a specific revision for a Gist file:

https://playground.open-rpc.org/?schemaUrl=https://gist.githubusercontent.com/[gist username]/[gist ID]/raw/[gist commit ID]/[file name]

Resources and Inspirations

• open-rpc/spec
• open-rpc/docs-react
• Swagger Editor
• Marvel Interactive Documentation
• apiary.io
• Algolia interactive documentation
• StackEdit in browser markdown editor
• Mou
• Stripe API Docs
• Monaco Editor
• Microsoft/vscode
• theia-ide/theia

Contributing

This project was bootstrapped with Create React App.

Available Scripts

In the project directory, you can run:

npm start

Runs the app in the development mode.
Open http://localhost:3000 to view it in the browser.

The page will reload if you make edits.
You will also see any lint errors in the console.

npm test

Launches the test runner in the interactive watch mode.
See the section about running tests for more information.

npm run build

Builds the app for production to the build folder.
It correctly bundles React in production mode and optimizes the build for the best performance.

The build is minified and the filenames include the hashes.
Your app is ready to be deployed!

See the section about deployment for more information.

Learn More

You can learn more in the Create React App documentation.

To learn React, check out the React documentation.

Contribution Resources

How to contribute, build and release are outlined in CONTRIBUTING.md, BUILDING.md and RELEASING.md respectively. Commits in this repository follow the CONVENTIONAL_COMMITS.md specification.

playground's Issues

update meta-schema to 1.0.0

• Need to update meta-schema

too many error messages blocks screen from being used

the height isn't capped.

should cap it to say 200px and then overflow: scroll

add favicon

• make a logo? use open rpc logo?

params descriptions dont render markdown

need to follow spec and try to render markdown for description

this ticket is a result of #36

add examples support

The automated release is failing 🚨

🚨 The automated release from the master branch failed. 🚨

I recommend you give this issue a high priority, so other packages depending on you could benefit from your bug fixes and new features.

You can find below the list of errors reported by semantic-release. Each one of them has to be resolved in order to automatically publish your package. I’m sure you can resolve this 💪.

Errors are usually caused by a misconfiguration or an authentication problem. With each error reported below you will find explanation and guidance to help you to resolve it.

Once all the errors are resolved, semantic-release will release your package the next time you push a commit to the master branch. You can also manually restart the failed CI job that runs semantic-release.

If you are not sure how to resolve this, here is some links that can help you:

• Usage documentation
• Frequently Asked Questions
• Support channels

If those don’t help, or if this issue is reporting something you think isn’t right, you can always ask the humans behind semantic-release.

---

No npm token specified.

An npm token must be created and set in the NPM_TOKEN environment variable on your CI environment.

Please make sure to create an npm token and to set it in the NPM_TOKEN environment variable on your CI environment. The token must allow to publish to the registry https://registry.npmjs.org/.

---

Good luck with your project ✨

Your semantic-release bot 📦🚀

Collapsible schema editor via pencil Icon

requires #31

docs dont render html tags

bump docs-react to get tags

https://github.com/open-rpc/docs-react/releases/tag/1.0.7

error on playground

HTML page will not render if $ref to external document is used

using $ref to external document will fail to render the document ( empty page , fail without errors ). I would suggest that it just put the document name there and still render the rest of the page.
"schema": {
"description": "",
"$ref": "somedocument.json"
}

configurable URL

should have a drop down that can configure the url

given a url, it should fetch the spec via service discovery

Allow a button to share links to the current playground document

Describe the feature
I'd like to click a button to copy a link to share it with someone else with the document I've edited.

Describe the solution
This can be done creating a button that when clicked, copies a new url with the document being edited passing ?schema=.

This feature is already used in the CLI:

playground/bin/cli.js

Line 47 in e973157

const url = `http://localhost:${port}?${qs.stringify({ uiSchema, schema })}`;

pristine this repo

Describe the feature you would like
This repo should be using pristine to get better baseline documentation and encourage contributions

Describe the solution
https://github.com/etclabscore/pristine#how-to-use-pristine-in-your-project

allow resize

I would like to be able to resize the split view

Semantic Release is not releasing to npm

Problem
Semantic Release is not releasing to npm

Solution

needs this inside of verifyConditions and publish in the .releaserc file

    "@semantic-release/npm",

and npm install --save'd

Electron Wrapper?

First Try notes

• reformat on a timer (3s after stopping typing) OR use a button to reformat
• show tooltips on the same timer??

support for uiSchema configuration (split view, auto expanding methods and params via toggles)

Describe the feature you'd like
I'd like to have a way to configure the expand or collapse state of the methods and their children.

Current Problem
they are closed now by default, but there is state.uiSchema.params["ui:defaultExpanded"] in App.js to configure this on and off.

Solution You'd like to see
I'd like to see it as both another checkbox toggle in the AppBar and via uiSchema object via querystring (theres an existing usage of qs already).
?uiSchema=

rename project to 'docs playground'

error in console: local references only!

this happens on latest meta-schema with the playground

Add ui initial state switching based on window.location

Should be able to provide different default UI layouts based on the url having
docs.myurl.com or myurl.com/docs should put the playground in docs mode
playground.myurl.com or myurl.com/playground should put the playground in playground mode

add CLI

Describe the feature
I'd like CLI interface to pass a schema to like:

npm install -g @open-rpc/playground
open-rpc-playground -s <schema>
// => Server listening on localhost:3000

fix CNAME for gh pages deploy on automated build

it probably needs to be copied in with the build to build/

errors in schemaToMarkdown when invalid params or result

The Future

semantic release gh pages error

[4:44:35 PM] [semantic-release] › ✖  An error occurred while running semantic-release: { Error: package.json repository.url does not match github.com pattern

missing `method.servers` support

playground should display errors for bad url

https://raw.githubusercontent.com/etclabscore/jade/7a49fdb20702a25fc67e5f08c85a822494199806/jade-service-runner-openrpc.json

Trying to use this json file on playground doesnt work, with no useful error message

convert to typescript

Is your feature request related to a problem? Please describe.
This project should be converted to typescript

Describe the solution you'd like
Go through and convert it to typescript

possibly pull out <Documentation /> to its own repo?

Additional context
This gets us a couple other things:

1. types from meta-schema
2. <Documentation /> usage in vscode plugin for Preview OpenRPC Document

Dependabot needs permission to see unicode-properties

Dependabot couldn't resolve your project's dependencies as it couldn't access unicode-properties.

You can provide additional git credentials in your Dependabot dashboard by clicking into the account menu (in the top right) and selecting 'Config variables'. If you use a custom token for the host github.com make sure it has read access to this repo, too.

You can mention @dependabot in the comments below to contact the Dependabot team.

allow outside contrib circleci tests via workflow

This worked with generator-client, here is the relevant line that allows fork PR's:

https://github.com/open-rpc/generator-client/blob/master/.circleci/config.yml#L26

but i dont think this works as it was edited (maybe by mistake?): in this commit:
open-rpc/generator@b09d9ea#diff-1d37e48f9ceff6d8030570cd36286a61

Summary column is empty for referenced parameters.

"Summary" of a parameter field will not be displayed in the generated HTML if the parameter is referenced as a component. ex
"params": [ { "name": "systemID", "required": true, "schema": { "$ref": "#/components/SystemID" } },
where
"components": { "SystemID": { "type": "integer", "title": "System ID", "summary": "My SUmmary",

it only works when I put the "summary" field directly in the parameter object in the params array. This is useful as there will always be redundant parameters, and you don't want to have redundant documentation for it.

Remove markdown in favor of MUI tables

Examples should be collapsible

Make examples section collapsible and when more than one example is given, create an arrow or indicator to show there is more then one example.

use semantic-release for releases

Is your feature request related to a problem? Please describe.
I'd like to spend less time releasing playground. Ideally this is an automated process.

Describe the solution you'd like
semantic-release has been added to some of the other repos. It should be added here too.

Additional Resources
#43

Add top right logo

on scroll fade in, scroll stop fade out

TypeError: Cannot read property 'getModeId' of null

Remove everything other than param and returns

just for now while we clean things up

Make Methods collapse into an accordion / cards

automate the deploy process

right now i am deploying by hand to github pages

the magical incantation goes something like this:

---

clean existing local gh-pages

git branch -D gh-pages

npm run build

remove build from .gitignore

checkout new branch, for example deploy/my-deploy

git add .

git commit -av

git subtree split --prefix build -b gh-pages

git push -f origin gh-pages:gh-pages

The automated release is failing 🚨

🚨 The automated release from the master branch failed. 🚨

I recommend you give this issue a high priority, so other packages depending on you could benefit from your bug fixes and new features.

You can find below the list of errors reported by semantic-release. Each one of them has to be resolved in order to automatically publish your package. I’m sure you can resolve this 💪.

Errors are usually caused by a misconfiguration or an authentication problem. With each error reported below you will find explanation and guidance to help you to resolve it.

Once all the errors are resolved, semantic-release will release your package the next time you push a commit to the master branch. You can also manually restart the failed CI job that runs semantic-release.

If you are not sure how to resolve this, here is some links that can help you:

• Usage documentation
• Frequently Asked Questions
• Support channels

If those don’t help, or if this issue is reporting something you think isn’t right, you can always ask the humans behind semantic-release.

---

No npm token specified.

An npm token must be created and set in the NPM_TOKEN environment variable on your CI environment.

Please make sure to create an npm token and to set it in the NPM_TOKEN environment variable on your CI environment. The token must allow to publish to the registry https://registry.npmjs.org/.

---

Good luck with your project ✨

Your semantic-release bot 📦🚀

add better JSON Schema support

right now for #36 its missing a couple features around schemas:

It does not go any deeper than schema.type.

anything other than the primitives are schemas defined in #components/schemas/<schemaName>

remove unneeded files

Describe the feature you'd like
serviceWorker and scripts/test.js are not used anymore

Always display summary docs

Create Extension pattern

We should support extensions within the playground. Examples are:

Method extensions - Items to attach to each method docs that will allow you to customize what you want included in your playground.

on first load with schemaUrl in url sometimes does not load

Describe the issue
on first load with schemaUrl in url sometimes does not load #231

Additional Information
the loading code is a bit of a mess.

Will rewrite with hooks which will make it a lot easier to handle the loading of state for the url and editor on load

remove appbar shadow

error messages sticking around

some of them dont go away after getting fixed. low priority but might as well document it

add error support