Adding categories in imported model

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?

Hey there,

I would suggest utilizing tags (https://docs.stoplight.io/modeling/modeling-with-openapi/grouping-tagging) to avoid modifying the underlying specification. In general, we don’t suggest modifying a spec for documentation purposes due to the reason you gave. Maintaining documentation that is out of sync with its underlying spec file can be a pain. With tags you can group your endpoints how you see fit. You can also hide endpoints (https://docs.stoplight.io/documentation/hiding-endpoints) and models (https://docs.stoplight.io/documentation/hiding-models) if need be.

Hey Robbins,

Thank you for the input. I have also thought about using tags but the development team is already using tags to group the endpoints. Not sure adding another tag would help, since Stoplight groups the endpoints by the first tag only. As I see it now, they will have to split the spec file into several smaller files, grouped by their respective categories.

Diana