Joi: Feature Request: Documentation generator

[builtbybrayne]

Context

• node
• standalone. (Not using Hapi)
• I use joi to validate all json messages in my microservice-based app. 90% in nodejs, but occasionally using embedded systems in IoT environment (e.g. Arduino) with support only for C and not NodeJS.

What are you trying to achieve or the steps to reproduce ?

I want to provide my C developers with readable documentation for the message format I expect them to send my NodeJS microservices.

So I want to pass my schema into a function and have a basic html structure returned which I can embed in a documentation site.

e.g.

function joi2html(schema) {
  ... This is the bit I need ...
}

const mySchema = Joi.object(.....);
const html = joi2html(mySchema);

Which result you had ?

I've looked around and the best I can find is Joi to JSON Schema, which I can then convert to docs. But I don't want to lose the expressivity of Joi, and I'm also using the https://www.npmjs.com/package/joi-extension-semver extension which isn't supported in json schema.

So, so far, I have nothing.

What did you expect ?

Well, it would be absolutely awesome if there was some doc-generation framework for Joi out of the box. So, it would automatically generates simple human-readable docs for the off-the-shelf Joi functionality, with an option to add handlers for extensions.

[AdriVanHoudt]

I don't think it would be something for the joi module itself but the idea seems cool.
For example https://github.com/hapijs/lout/ does this for hapi but I assume it has a basic joi parser thing built in it that you can use as an example

[WesTyler]

@perchten I agree, this is highly unlikely to end up in Joi itself.

Do you mind if I close this out? You can join us on the gitter to talk about it more if you haven't already! :)

[DavidTPate]

Yeah, I definitely agree as well. This seems beneficial but I wouldn't expect it to be part of Joi.

@perchten feel free to reach out, it's likely that the describe() functionality will be very useful here.

[jacobworrel]

For anyone who might be interested, I published a package that parses Joi schemas and generates markdown files. It's still in a pretty early stage of development so only part of the Joi API is supported. If you feel like contributing, feel free to hit me up or open a PR.