chore: doc, tests, lint

* documentation update to meet go-openapi standards
* fixed discord link
* relinted godoc and markdown

* relinted the codebase (many nolint directives are set, the design
  can't be changed easily)
* simplified test assertions for JSON & YAML (replaced ad'hoc helpers by
  testify/v2 features)

Signed-off-by: Frederic BIDON <fredbi@yahoo.com>

Author: fredbi