Can I create rich, dynamic “Implementation Notes” in swagger?

Question

I'm currently using ApiOperation annotation for documenting my web services methods in the "Implementation Notes" section:

@ApiOperation(
    value = "Searches for information",
    notes = "This service searches for information"
)
public Response getInformation(...)

I want to enhance my notes now to use properties files, information from a database, etc. I want it to be rich and dynamic.

So, let's say I have a POJO that contains information from the database:

@Entity
public class SortColumnField {
    @Id
    @Column
    private String fieldName;
    @Column
    private String fieldDescription;
}

Is there something that would allow me to generate swagger documentation from objects such as this?

Answer 1

You have two choices for doing this.

First, the notes section supports markdown, specifically github-flavored. You can have fairly rich information in that section and most tools will render it correctly.

Next, the Operation Object supports a field called externalDocs . While not rendered in Swagger-UI, you can easily fork the UI to reference your complex documents which may not fit in the structure that is rendered in the standard tools.