Generate API documentation about blitz HOT 13 CLOSED

Ok sounds like it shouldn't even be part of the blitz app. So not as an auto generated page, but as a standalone site.

And seems like maybe there's two main use cases:

1. blitz docs -> Opens docs in browser with hot reloading
2. blitz docs export ~/some/path/myDocs -> Exports a full static site that can you can do anything with.

from blitz.

Related discussion: #1907

from blitz.

Thanks @mbrookson, generating API documentation is a great idea! Someone can definitely work on that at anytime.

I also think generating clients is a good idea, but let's keep this issue focused on the docs part.

from blitz.

Love this idea! Might hop on it. @mbrookson Are you looking for a page to be generated, so that people can go to something like localhost:3000/api, or something more like a Markdown file?

from blitz.

just stepped over this issue. This idea is super cool!

Having a recipe for generating a dokz page as part of the application would be a dream come true, but perhaps for the beginning we could try to generate an openapi yaml/json and offload the integration to the enduser.

from blitz.

@merelinguist A generated page would be ideal and probably more flexible as more functionality could be added in the future I guess? Markdown would be useful still, but doesn't have quite as much potential for further features later on.

from blitz.

@merelinguist Maybe the web page could be driven via a markdown file though? Best of both worlds, plus you could also then choose to do other things with the markdown if you wanted, like generate a client.

from blitz.

The other question is how to distribute it. Does it only show during development? In production behind authentication? As a standalone static docs site?

from blitz.

@ryardley Any idea how simple it would be to inject a page like this?

from blitz.

I’d be pretty reticent to have it in production, especially if it’s supposed to be more of a handy dev tool than “here’s a guide to our complete private api”.

from blitz.

Yeah that's an interesting point. Perhaps could be an option? You might want to expose docs for a public API in some instances.

Getting a bit more complex here and just throwing out ideas, but perhaps it could even be per endpoint? Each function could be marked as to whether it should be exposed in public docs. For an initial implementation I'd probably err on the side of caution and keep it private and only available during development.

Also in regards to how it's distributed, standalone would probably be better. Doesn't seem ideal to have to run the application just to be able to view the docs when you're actually only focused on the development of a separate mobile application. On the other hand. Perhaps the docs could be generated using a separate CLI command, run standalone, and be able to be put into a git hook so they can be generated on commit.

from blitz.

Thanks @mbrookson, generating API documentation is a great idea! Someone can definitely work on that at anytime.

I also think generating clients is a good idea, but let's keep this issue focused on the docs part.

Hello! You can see deployd.com this framework that I have been used is fantastic! I developed a full stack based on riot.js, deployd, semantic ui and others... My stack is very simular with blitz.js! I'm studying blitz.js and I'm in love with it :)

from blitz.

Hi team any progress for this feature?

from blitz.