Generate API Docs for Custom Collections in Directus

Speaker 0: Alright. Alright. Welcome back. We are live on the Directus community hotline. I'm your host, Brian Gillespie.

Today, we are answering a question from community member RHB. RHB, what's up, sir? Glad to have you inside the community. Let's get to your question. Thanks.

But is there an automated way to generate API docs for my custom collections inside Directus? The open API spec that generates that Directus generates is massive, and 99% of it is system stuff I don't need. I just want clean docs for my own collections like products, customers, services, etcetera. Anyone know of a tool or script that could filter the OpenAPI spec to only include my collections? Or maybe there's a better approach entirely.

Well, I'm not sure of a tool or a script, but I can give you a better approach. Let's dive into it. So, this is familiar to probably everyone. This is like the swagger spec. This is kind of the out of the box API documentation.

This is just their pet store demo. But, one of the nice things about Directus, I know I say this a lot in videos, is the ability to generate this open API spec. So I could just come to server slash specs slash o s and get the full open API spec. It's beautiful. Now, it is very comprehensive in that every single API endpoint that the current user has access to will be shown here.

So we can kinda see which way we're leading here. The easiest way to get a filtered list for your API spec is just to use a user to grab the API spec that has lowered permissions, restricted permissions, permissions just to the collections that we want in the spec. So how can we do that? We're gonna go into Directus settings, and I'm just gonna create an access policy for this. Now technically, again, just use any user that has the correct permissions that you want and generate the open API spec.

But to make this super clear, we're just gonna generate a new policy called API spec, and I'm gonna add two collections to this. Just pages will give all CRUD access. Not trying to print the page. We'll do posts. Great.

We'll give all CRUD. We'll take away the shares. I don't typically use those a lot. Okay. So now we'll we've got this policy.

We're gonna go in and create a user, And I'm just gonna call this one, surprise surprise, API spec user. Great. What do we need to actually pull this off? Right? We don't have to add a role.

Directus 11 was really nice in that, we got permission or we got support for access policies. So we can, roll up policies up to the role level or I could just add them directly to specific users in this case. So we're just gonna add API spec. I'm gonna generate a token. And now I'm gonna hop over to Swagger and I'm gonna add my directus URL.

I'm going to go to this endpoint, server slash specs slash o a s, and I'm gonna add a query param for access token. Now this is definitely, do what I say, don't do what I do. Adding the access token as a query param is not safe, doing it just for demonstration purposes here. Make sure, you know, you're passing that as an authorization header, for the bearer token. So I'm just gonna hit explore and server specs OAS.

Let's try again. Grabbed the token. Got the API spec. Save. Explore.

Server spec. Forgot an s. Gotta get the s in there. Okay. So now we're going to see, we'll see the authentication endpoints just because those are always available.

Right? The server health endpoints. Okay. Great. But if I take a look now, I don't see a giant list of endpoints.

I just see pages and I just see posts. And, again, I can use Swagger to test those out, but this is the best way to filter down that list, without running extra scripts or extra processing on it. So RHB, I hope this is helpful for you, man. The other thing that I wanna show you, if you go into the marketplace, we've got several extensions that could get the job done for you as well potentially. So if you just search rapid in the marketplace, there's an API viewer extension, a rapid docus extension that allows you to view that open API spec without ever leaving the Directus App Studio.

If you would like your question to be featured on Community Hopeline or you just have Directus questions in general, hop into our community at community.directus.io. Post your question and you may be featured on the next episode. We'll see you.