Instructions and/or documentation for swagger REST doc generation

@pascal, when you have time it would be great to have some documentation, instructions, or guidance about how the swagger rest documentation generator works.

Even the smallest amount would be helpful as a starting point.

I’m personally interested in two things:

  1. If I find a mistake in the docs, is there something I can easily do to fix it (without much time investment, while doing something else)
  2. Are there general guidelines we should follow in our resources that make them more documentable? E.g. if we automatically document @SearchHandlers, but can’t document behavior of the search method, should we start refactoring our code guided by that? Or would we just need to but some textual annotation on the search method to document how it works?

There are some docs in this repo. Specifically, look at the swagger-ui branch.

In response to your questions:

  1. It depends. If it’s static (unlikely), you can make the change in the swagger-ui branch above. If it’s something that’s dynamically generated, you’ll probably have to make the change in SwaggerSpecificationCreator.java.

  2. I don’t have a good answer to this. The docs are currently created using some hacky reverse engineering. The ideal solution would be to generate the docs using something like annotations.