Revision history [back]

To create Swagger documentation that displays the response details of an abstract class, you can use the following steps:

1. Define the abstract class and its properties in your code, and provide examples of the expected response data.

Example:

import java.util.List;
import com.fasterxml.jackson.annotation.JsonSubTypes;
import com.fasterxml.jackson.annotation.JsonTypeInfo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(value = "Animal", description = "Abstract class representing an animal")
@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "type")
@JsonSubTypes({
    @JsonSubTypes.Type(value = Dog.class, name = "dog"),
    @JsonSubTypes.Type(value = Cat.class, name = "cat"),
})
public abstract class Animal {

    @ApiModelProperty(value = "The name of the animal", example = "Max")
    private String name;

    @ApiModelProperty(value = "The age of the animal", example = "3")
    private int age;

    @ApiModelProperty(value = "A list of the animal's favorite activities", example = "[\"running\", \"swimming\", \"playing catch\"]")
    private List<String> activities;

    // Getters and setters for the properties
}

@ApiModel(value = "Dog", description = "A type of animal that represents a dog")
public class Dog extends Animal {

    @ApiModelProperty(value = "The breed of the dog", example = "Labrador Retriever")
    private String breed;

    // Getters and setters for the properties
}

@ApiModel(value = "Cat", description = "A type of animal that represents a cat")
public class Cat extends Animal {

    @ApiModelProperty(value = "Whether or not the cat has claws", example = "true")
    private boolean hasClaws;

    // Getters and setters for the properties
}

1. Add annotations to your code to specify the Swagger documentation for your abstract class and its subtypes.

Example:

@ApiOperation(value = "Get an animal by ID", response = Animal.class)
@ApiResponses(value = {
    @ApiResponse(code = 200, message = "Successfully retrieved animal", response = Animal.class),
    @ApiResponse(code = 404, message = "Animal not found")
})
@GetMapping("/{id}")
public ResponseEntity<Animal> getAnimalById(@PathVariable("id") Long id) {
    // Code to retrieve an animal by ID
    return ResponseEntity.ok(animal);
}

1. Generate the Swagger documentation for your API using a tool like Swagger UI.

Example:

swagger: '2.0'
info:
  title: Animal API
  version: 1.0.0
paths:
  /animals/{id}:
    get:
      summary: Get an animal by ID
      operationId: getAnimalById
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          description: ID of the animal to retrieve
          required: true
          type: integer
          format: int64
      responses:
        '200':
          description: Successfully retrieved animal
          schema:
            $ref: '#/definitions/Animal'
        '404':
          description: Animal not found
definitions:
  Animal:
    type: object
    discriminator:
      propertyName: type
    properties:
      name:
        type: string
        example: Max
      age:
        type: integer
        format: int32
        example: 3
      activities:
        type: array
        items:
          type: string
          example: running
      type:
        type: string
        example: dog
    required:
      - name
      - age
      - activities
      - type
  Dog:
    allOf:
      - $ref: '#/definitions/Animal'
      - type: object
        properties:
          breed:
            type: string
            example: Labrador Retriever
    required:
      - breed
  Cat:
    allOf:
      - $ref: '#/definitions/Animal'
      - type: object
        properties:
          hasClaws:
            type: boolean
            example: true
    required:
      - hasClaws

1. Test your API documentation by using the Swagger UI tool or by making test requests to your API.