cancel
Showing results for 
Search instead for 
Did you mean: 

Swagger multiple definitions best practices

Highlighted
Frequent Visitor

Swagger multiple definitions best practices

I posted this same question to Stack Overflow but it didn't get any attention:
https://stackoverflow.com/questions/64790650/swagger-multiple-definitions-best-practices 

 

I have an API, and a consumer web app, both written in Node and Express. The API is defined by a OpenAPI Specification. Implemented by swagger-ui-express[1].

The above web apps are Dockerised and managed in Kubernetes.

The API has a handful of endpoints for managing the lifecycle of a user's registration/application to the service.

Currently, when I need to cleardown completed/abandoned applications, or resubmit failed applications, I employ a periodically run cronjob to carry out a database query for the actions mentioned. The cronjob is defined by a Kubernetes config YAML file. This is quickly becoming unmanageable, and hard to maintain.

I am looking in to having a dedicated endpoint for each of the above tasks. Then a dedicated cronjob could periodically send a request to the API endpoint to carry out the complex task. This moves the business logic back in to the API, and avoids duplication within a cronjob hosted elsewhere. I am ultimately asking if this is a good approach or is there a better workflow documented somewhere I could implement?

My thinking is that I could add these new endpoints to the already-existing consumer API, but have the new (housekeeping/management) endpoints separated from the others.

To separate each (current) endpoint in to their respective resource, I am defining tags within the specification. Tags don't seem to be sufficient for the separation of these new "housekeeping" endpoints.

Looking through the SwaggerUI documentation[2] I can see that I can define multiple definitions (via the `urls` property) to switch between. These definitions being powered by individual Specification documents. This looks like a very clean way of separating the consumer API from the admin API, is this best practice?

Any input would be appreciated on this as I am struggling to find much documentation on this kind of issue.


[1]: https://www.npmjs.com/package/swagger-ui-express
[2]: https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md

New Here?
Join us and watch the welcome video:
Announcements
Top Kudoed Authors