Swagger for Apostrophe.

[kklicmhenya]

Hello everyone! I am currently working on my project based on ApostropheCMS and I need to have good documentation of all Routes, how can I competently connect swagger to ApostopheCMS?

My main problems are not availability of getting the app object.

apos.app.use()

I use those docs:
https://medium.com/@samuelnoye35/simplifying-api-development-in-node-js-with-swagger-a5021ac45742
https://docs.apostrophecms.org/reference/modules/express.html
https://www.npmjs.com/package/swagger-ui-express

[BoDonkey]

There is also a section in the documentation for the REST API endpoints. Not sure what else you would be looking for. Other than that I guess you will also have to consider routes created in your project through the module customization functions like routes(), apiRoutes(), and restApiRoutes(). here

[kklicmhenya]

Thanks for answer!

Yes, I saw that there is a page describing rest api apostrophe, but I want to understand how I can correctly get the app object and customize the swagger for the project.

[boutell]

Hi @kklicmhenya,

As you say the Express app object is available, as apos.app. I see from the Swagger documentation that you'll need this in order to do apos.app.use.

However there is another issue. There is a catch-all route in Apostrophe which tries to serve a URL as a page if it isn't found otherwise, and finally a 404 is sent.

So to avoid that you need to register your route early. You can do that by using self.apos.app.use in the init() function of your own module, let's say it's modules/swagger/index.js. Make sure you add your module to app.js as well.

[kklicmhenya]

Thanks for answer! I will try it.

[kklicmhenya]

@boutell
Yes, it works for me! Thanks!

But last question is: where I can take the path to apostrope default routes? Maybe you know?

const swaggerOptions = {
        swaggerDefinition,
        apis: ['./routes/*.js'], // Path to the API routes in your Node.js application
      };

[boutell]

It looks like Swagger wants to be given source files and doesn't analyze the existing app object's routes or similar.

As such I don't think this is going to work because it's not going to find what it expects, Apostrophe's apiRoute function provides conveniences that go beyond standard Express which Swagger probably isn't going to be compatible with out of the box.

[kklicmhenya]

Got it! Thanks!