chore: doc, tests, lint (#255)

* 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)
* test: worked around windows-specific data race issue in tests (used
  embed fs to avoid windows FS issues)

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

Author: fredbi