Jiga

We started generating Swagger 3 documentation (OpenAPI 3.0) for our API service using SpringDoc. We are also using Spring Hateoas to include links within the response for easy navigation.

The generated schema includes the 3 examples of “_links” object for each model classes that extends RepresentationModel in your response.

Here is a shortened example of what we were seeing:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "string",
  "type": "string",
  "marks": 0,
  "teacher": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "_links": {
      "additionalProp1": {
        "href": "string",
        "hreflang": "string",
        "title": "string",
        "type": "string",
        "deprecation": "string",
        "profile": "string",
        "name": "string",
        "templated": true
      },
      "additionalProp2": {
        "href": "string",
        "hreflang": "string",
        "title": "string",
        "type": "string",
        "deprecation": "string",
        "profile": "string",
        "name": "string",
        "templated": true
      },
      "additionalProp3": {
        "href": "string",
        "hreflang": "string",
        "title": "string",
        "type": "string",
        "deprecation": "string",
        "profile": "string",
        "name": "string",
        "templated": true
      }
    }
  },
  "_links": {
    "additionalProp1": {
      "href": "string",
      "hreflang": "string",
      "title": "string",
      "type": "string",
      "deprecation": "string",
      "profile": "string",
      "name": "string",
      "templated": true
    },
    "additionalProp2": {
      "href": "string",
      "hreflang": "string",
      "title": "string",
      "type": "string",
      "deprecation": "string",
      "profile": "string",
      "name": "string",
      "templated": true
    },
    "additionalProp3": {
      "href": "string",
      "hreflang": "string",
      "title": "string",
      "type": "string",
      "deprecation": "string",
      "profile": "string",
      "name": "string",
      "templated": true
    }
  }
}

Although this isn’t entirely wrong, this clutters the schema and takes up 90% of the space.

To hide all the “_links” object from the schema, we simply have to use the addResponseTypeToIgnore method on the SpringDoc utils config. This method wasn’t mentioned in the documentation.

Here is the full configuration:

@Configuration
public class OpenApiDocs {

    @Bean
    public OpenAPI meteoriteOpenAPI() {
        SpringDocUtils.getConfig().addResponseTypeToIgnore(Links.class);
        return new OpenAPI()
                .info(new Info().title("Meteorite API")
                        .description("Meteorite API documentation. This API intended to be used by Meteorite staff mobile apps and Meteorite customers.")
                        .version("v1.0")
           );
    }
}

Once this is done, regenerating the documentation shows our original schema now without the _links noise:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "string",
  "type": "string",
  "marks": 0,
  "teacher": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string"
  }
}