Tangent Question: Postman vs Swagger UI vs Insomnia

What do you use or recommend for Rest API Documentation, Guides, Snippets, and Collaboration?
Might have an implementation for Postman + Directus + GitHub!
Curious to learn about Swagger UI though.

Spoiler on this feature was made in youtube video 👍

"... and also with an API reference that is dynamic to your schema"

😏

https://docs.directus.io/reference/api/introduction/

Link not valid.

https://docs.directus.io/reference/introduction/

Hi @Guiqft, firstly thanks for sharing your code.

But this isn't the code from your extensions js file, is it?
Because when i tried this (in my docker based setup, it doesn't work in my setup at all (error: 'can't use import statement', can't import the npm modules with require either).

Hi @arladmin. Yes, it's my .ts from extensions file. You should try the new create extension command from the directus extensions sdk and paste my code into the main .ts file. This hould work as any custom endpoint.

I don't understand something. You seem to be referring to a static JSON file, however the /server/specs/oas endpoint is dynamic.

Any idea how to reference the dynamic content and pass the authenticated/authorized session to that endpoint so it'll return the JSON the user is actually to see?

The endpoint obviously doesn't have the same session as the app. I'm thinking there is no way/extension to overcome this at the moment?

FWIW, this is my extension code so far:

const swaggerUi = require('swagger-ui-express');

module.exports = function registerEndpoint(router, context) {
  const { ForbiddenException } = context.exceptions;
  router.use((req, res, next) => {
    if (!req.accountability.user) {
      throw new ForbiddenException();
    } else {
      next();
    }
  });

  const options = {
    swaggerOptions: {
      url: '/server/specs/oas',
    },
  };

  router.use('/', swaggerUi.serve);
  router.get('/', swaggerUi.setup(null, options));
};

@keesvanbemmel if we check the existing endpoint which you mentioned as dynamic, we can see it is using SpecificationService:

which is available in context.services, and the accountability usage here should be what you need.

Then you should be able to pass the generated Open API Object (Reference for source code) from the generate() function (line 18 of the code shown above) to the swaggerUi.setup function.

Disclaimer: never personally tried the above code/suggestion, but on paper it should work. Let us know how it goes

Any updates on this? Would love to evaluate this!

I believe we already have this:
https://docs.directus.io/reference/system/server/#get-openapi-specification

I think this is about HTML API docs @benhaynes

Hey @benhaynes, that's already great; I was hoping for a way for Directus to autogenerate a OpenAPI / Swagger HTML documentation from that spec.

Hmm, not sure about that... maybe @rijkvanzanten knows. All I know is that we are working on getting these to generate in the App (markdown -> HTML), if that's what you're looking for.

No news... but I agree this would be a great addition to the platform!

As stated here :

There's currently no way to have custom endpoint inject definitions into the generated specs

I'm sure with a bit of creativity we can make it happen, and then add these new endpoints to the /server/specs/oas (or to a separate route ?) and reuse that data to display endpoints on the /admin/settings/extensions page 🙌

I'll look into it but can't promise anything, if anyone wants to contribute, I guess all new ideas and pieces of code are welcome 👀

Another approach would be to make a custom extension that does "only" that job, maybe

EDIT: Found that repo, will give it a try https://github.com/sacconazzo/directus-extension-api-docs