Is the API reference generated or created manually?

[thim81]

Hi,

The https://docs.directus.io/ look really great & clean.

I was wondering how do you maintain the API reference part?
Is this generated based on an Swagger/OpenApi specification or manually written?

Regards,
Tim

[benhaynes]

We use VuePress and maintain everything in markdown docs that we write manually. In the upcoming v9 we'll be moving to OAS/Swagger and or other tools for that.

[rijkvanzanten]

All handmade Markdown in a custom VuePress theme 👍

[thim81]

I'm curious what tools you are going to use?

Currently I use:

• OpenAPi > Redocly for API reference
• OpenApi > openapi-to-postman > postman collection

[rijkvanzanten]

I'm not sure yet. Also not 100% convinced that just the OpenAPI spec is flexible enough to write the full API reference in. There's a lot of cases where I want to add in additional info that's a little more free-formatted 🙂

[thim81]

The current https://docs.directus.io/ is much richer then just an API reference.

You can do a lot with the "description" field in OpenApi but not go fully styled like you are doing with VuePress. You could use "x-" vendor tags in the OpenApi spec and customize the rendering to support a richer format.

[WoLfulus]

@rijkvanzanten I used https://apiblueprint.org with aglio years ago. There might be better renderers atm.

[rijkvanzanten]

I'm setting up the whole spec in https://paw.cloud/ now which in turn can export to OpenAPI / API Blueprint etc 🙂