Adding categories in imported model

(Dbrebu) #1

Our API spec is really huge, so the development team asked me to refactor the code-based documentation, and group the various resources by their scope. I was thinking about the following approach:

  1. create a separate model for each group of resources
  2. add a general API Reference page (Page Type - Embedded)
  3. add subpages under API reference that will be set as OpenAPI and will link to the previously created models

Considering that the development team will keep the initial API spec, without the scope groups, I am not sure if there is any other way I can incorporate changes to the spec except for manually tracking the changes and adding them in Stoplight.

Do you see any other approach to this problem? Is it possible to modify the imported model so as to include the resources grouped by scope? And, if so, how can I make sure the OpenAPI spec and the Stoplight documentation stay in sync?