V8-archive: API Documentation

[simivar]

Feature Request

Option to generate API Documentation for Open API/ ReDoc.

What problem does this feature solve?

When you are creating API that can be used publicly/shared with 3rd party you want to share your API documentation with them. Currently, from what I gather, it is not possible with Directus. I think that option for generating Open API / Redoc would be great addition. Right now, as an 3rd party, it is hard to grasp the API schema.

How do you think this should be implemented?

Generate OpenAPI-compatibile JSON with API Documentation when updating database schema.

Would you be willing to work on this?

If enough details provided here so that I can contribute as first issue - sure.

[hemratna]

Hi @simivar We tried to develop similarly in the past. But we face specification issue with Open API. You can check the issue https://github.com/OAI/OpenAPI-Specification/issues/1706

Let me know your thoughts.

[simivar]

Thanks for such fast reply. I see a few roads that we could take but the one that I think stands out is to generate, if that's possible, OpenAPI documentation for database-generated endpoints and redirect users to Directus docs for directus-specific endpoints like filters.

That way:

1. we don't move from widely adopted specification of OpenAPI
2. we can patiently wait for better times when OAI/OpenAPI-Specification#1706 gets implemented
3. every endpoint in our project is documented and we can share that with 3rd parties

Of course it still won't be possible to use Code Generators etc. but at least we would have everything documented.

[benhaynes]

I'm curious if this is similar to my idea of "auto-docs":

https://github.com/directus/app/issues/797

I was thinking it would be nice to generate a markdown file that could be rendered as HTML in the App/browser so you had dynamic Docs for your API (based on your specific schema). Is this what you're looking to accomplish, or is the OAS output different?

[benhaynes]

We could move that referenced issue to the api repo and have it be an endpoint that returns everything in .md too. Thoughts?

[simivar]

I am trying to accomplish the same thing but I specified it to OAS so we could use any of Documentation tools available for OAS like ReDoc, readme or others.

I think that would be easier to do as we won't have to do own template or anything and it would be first step to introduce full OAS support (when deepObject issues get solved).

[benhaynes]

Makes sense. The problem is that OAS does not support our syntax for filtering, which is obviously a huge part of the API. Also, not sure how it would handle our newer GraphQL endpoint. So we can either follow that spec _when possible_ or find something that works best for our system.

Also, this option would require a third-party tool to generate the Docs (it's basically returning JSON schema to spec), while what I was proposing returns markdown based on template files (which could be extended, too). So I wonder if these are two different things — or where the overlap should be.

[hemratna]

For the GraphQL, It will be self-documented from its schema.
So I think there is no need to add GraphQL in the OAS.
If needed, we can add the link of the GraphQL endpoint (which is only one /gql) in the documentation.

[hemratna]

@benhaynes Regarding the OAS along with markdown, We can use some tools which support both like http://dapperdox.io/docs/author-concepts

I had not experienced with Dapperdox yet. But it looks like with this we can have the best in both worlds.

[benhaynes]

Sounds good! I'm less concerned with OAS due to its limitations, but it's a good spec otherwise.

[benhaynes]

To achieve better clarity/visibility, we are now tracking feature requests within the Feature Request project board.

This issue being closed does not mean it's not being considered.