Generate API documentation

[mbrookson]

What do you want and why?

When building a full stack application, it's common for it to grow into something much more. For example, a companion mobile application is often part of a website and backend ecosystem. It would great if Blitz expands to accommodate this use case more and generate easy-to-user documentation or client which can be used to build external clients that utilise the generated Blitz API.

Possible implementation(s)

• Generate API documentation from the API functions that Blitz generates at build time.
  • This could include all API routes and schema for query strings and POST request bodies.
• Generate a TypeScript API client so you can just import and start calling the API externally?
  • e.g. Implementations for axios or pure fetch API?
  • Not sure how but even an ability to generate something for use outside of JS? For example what if you wanted to build your app with Flutter?
• Include examples for common use cases
  • e.g. how to authenticate an external client

Additional context

I have something like swagger.io in mind, however I'm sure it could be far greater!

Example:
https://petstore.swagger.io/?_ga=2.158440947.899930001.1594640979-1996492643.1594640979

[flybayer]

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.

[merelinguist]

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?

[mbrookson]

@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.

[mbrookson]

@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.

[flybayer]

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

[merelinguist]

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

[merelinguist]

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”.

[mbrookson]

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.

[flybayer]

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.

[sakulstra]

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.

[Skn0tt]

Related discussion: #1907

[bitec-projects]

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 :)

[Gnosnay]

Hi team any progress for this feature?