Closes #1075.

So the comments will appear in i.e. pkg.go.dev and IDEs.

To make it easier for our users to understand the configuration options
that they're able to use, we can introduce a JSON schema that can be
used by an IDE or Language Server Protocol (LSP) implementation to
validate + provide autocomplete.

We make sure to use `additionalProperties: false` to make it super clear
when there's no additional properties possible, which will also make it
clearer when we have items in our configuration which may not be valid,
or from a newer version of `oapi-codegen` that's in use.

Closes #1546.

Now we've got a JSON schema (via #1546) we can use for IDE visibility
into fields, we should apply it to all our configuration.

We'll use the `yaml-language-server` config as that's what I'm using
locally.

I've been thinking for some time we should rethink the documentation
we've got, as it's been feeling a little bit underdocumented, a bit of a
mixed voice, and we've also had not-that-actionable examples for all the
functionality.

This is the culmination of ~7 weeks of rewriting, alongside the addition
of new examples.

Closes #1254.

Co-authored-by: Jamie Tanna <jamie.tanna@elastic.co>