0

I have a spring boot application using spring data rest. I have a problem in providing a well read API documentation using swagger. I tried spring fox and springdoc, but each has its problems

  1. Spring fox:
  • I can not change the tag name of a repository, only the description
  • No support for projections
  • No support of openAPI3 yet (this is actually not a big problem)
  1. Springdoc (https://springdoc.org/)
  • I can not change neither the tag name nor the description (@Tag does not work on repos)
  • No support for projections
  • The same repo gets 3 tags e.g. books-entity-controller, books-search-controller (with methods of a parent class) and books-property-reference-controller (with unnecessary listing of /{id}/{property} urls)

Any better way? I like spring fox for not providing more than one tag, also the auto generated tag names are better e.g. Books Entity instead of books-entity-controller. But it would be better either to customize it or find a better alternative.

Rasha Elsayed
  • 660
  • 1
  • 7
  • 22

2 Answers2

1

I recommand Spring REST Docs over Swagger. Spring REST Docs is test-driven to guarantee your API documentation is always sync with your API. Andy's talk explains more why Spring REST Docs is more suitable than Swagger for API documentation.

You can find offical simple guide and more samples.

My Github project uses it. You can clone the repository and have a look at the generated documentation HTML /sga-booking/index.html. Related Spring REST Docs file are

If you find my Github useful, consider give it a star.

yejianfengblue
  • 2,089
  • 1
  • 14
  • 18
1

Springdoc

I can not change neither the tag name nor the description (@Tag does not work on repos)

and

The same repo gets 3 tags

You can customize it. Use the following at the controller-class level.

@Tag(name = "Name of the Tag", description = "Description of the tag")

or

@Tags(value = {
    // Multiple @Tag annotations separated by comma ,
})

or the following at the method level.

@Operation(tags = {"Tag 1", "Tag 2"})

Remember:

  • @Tag at a class level will override the operation level tags for the particular class.
  • A class level tag can have only 1 value.

So if you need a controller to have multiple tags, you should isolate it in a different class that doesn't have the @Tag at the class level.

No support for projections

I have never used projections. I generally use the @JsonIgnore to eliminate the ones not needed, but depends on your use-case.

If you want to hide something from a schema, use can use the below method

@Schema(description = "Example POJO to demonstrate the hidden attribute")
class Example {
    ...
    @Schema(hidden = true)    // <--- Will be hidden from the Swagger UI completely 
    String exampleId;
    ...
}

Hope that helps. Drop a comment for any clarification.

Debargha Roy
  • 2,320
  • 1
  • 15
  • 34