Difficulty in maintaining large OpenAPI Specs

[AniketGroww]

@lbroudoux , so for now, for a service say A, we have 10 apis, now each api has a request body and for that request body there are multiple response examples.
So, when we are maintaining an open api spec yaml, it comes around 2000, 3000 + lines, debugging and maintaining of which is very difficult. Postman collection is an option but again, there we cannot maintain dispatching rules, we have to import it seperately.
Is there any solution for this or any idea that you can share with us via which we can solve this ?

[lbroudoux]

Hey @AniketGroww,

I feel the pain of maintaining large OpenAPI files - the Microcks OpenAPI spec currently has something like +2100 lines. 😉
There shouldn't be a single one-size-fits-all response out there, especially because it depends on your flow and on the persons who maintain the artifacts. In my opinion, there are some options to consider, though:

1. Invest in design tooling: look for a tool (like Apicurio Studio or Postman API Designer, for example) that abstracts the file vision and helps the designers focus on scoped fragments (path, operation, data type, ...) while providing utilities for generating example skeletons

2. Invest in bundling/un-bundling tooling that allows you to aggregate/split OpenAPI fragments at the file level (BTW, it can be done by your visual design tool too, but not especially related). This allows you to work on smaller fragments and avoid conflicts in a team. However, you may also have to invest in linting/governance tools to ensure the global consistency of the fragments

3. Consider splitting/introducing other kinds of artifacts with different lifecycles. Typically:

• Put the common types definition in JSON Schemas,
• Keep the paths/operation definition in OpenAPI Specs,
• Use one or many Postman Collections to gather examples for different related operations (you may also split by group of operations)
  These artifacts may still be imported together or independently in Microcks to rebuild a comprehensive API and its mock vision

4. Consider splitting your API definition 😉 If you cannot easily maintain it, maybe it has grown too big with loosely coupled stuff that may require being split into different OpenAPI specs

There may be some other options to consider out there. I'll call some friends for advice.