Skip to content
This repository has been archived by the owner on Apr 29, 2019. It is now read-only.

Proposal: Augment dna.json to support clearer auto-generated api documentation #97

Open
wants to merge 3 commits into
base: develop
Choose a base branch
from

Conversation

neonphog
Copy link

@neonphog neonphog commented Jun 5, 2018

Please see the changes to dna/dna.json:

  • Addition of ReturnType to Functions items. Note holochain currently returns text/plain content-type for all calls (even if they return json data), hence everything for clutter marked as string.
  • Addition of InputSchemaFile to Functions items that have a CallingType of json. This gives us more information about the expected parameters.
  • Addition of OutputSchemaFile to Functions items that have a ReturnType of json. Unused at the moment (given holochain always returns text/plain) but can in the future give us an indication of output data format.
  • Addition of Description to Functions items. This is a string (potentially markdown) that can give a more verbose indication of what functions do / how to use them.

Notes on accessing the api-docs:

  • Works with the development server npm start... simply navigate to http://localhost:3000/clutter-api-docs.html
  • Does NOT work with the production build, hcd/hcdev hosted ui site. Afaik we would need to eject the create-react-app environment to get the service-worker et all to stop overwriting the path with index.html. If anyone has another solution (ejecting adds a big configuration management overhead) would much appreciate it.
  • You can also just navigate to the docs with file://, but you'll need some cors fixes: add cors headers to ui/webserver fn responses holochain-proto#741

@ddd-mtl
Copy link

ddd-mtl commented Jun 5, 2018

To add to that I would also add the Description to Entries. And For Entries of type links, I would add more fields to describe the base, link and tags like I did in HoloChess.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants