Control Grouping with Swagger

Gelato's Swagger Extensions

Gelato supports a couple of Swagger extensions (via x- prefixed parameters, which are part of the Swagger Specification). These allow you to do special things with your Swagger file and Gelato.

Control Grouping with Swagger

Gelato "groups" your API Paths into Resources to make things easier for your developers. Normally we'll do this automatically by looking at your Swagger Paths. For example, if you had:

  • /rabbits
  • /rabbits/{rabbitId}
  • /bison
  • /bison/{bisonId}

Gelato will create two Resource groups for you (Rabbits and Bison). Your Portal navigation will look like this:

Navigation Example

You can customize this grouping by adding an x-gelato-group property to one of your paths:

  "paths": {
    "/rabbits": {
      "x-gelato-group": "Small Animals",
      "get": {
        ...
      }
    },
    "/bison": {
      "x-gelato-group": "Large Animals",
      "get": {
        ...
      }
    }
  }

After an import, this will result in your Portal Navigation showing up like this:

Custom Grouping Example

And this will be repeated automatically each time you update your Swagger Definition. Awesome, right!

Any questions?

As always, if you're having trouble with Swagger or you'd like some help with Swagger and Gelato, you can send us an email!.