kin-openapi VS swagger2markup

We'll use the excellent kin-openapi Go library to convert the OpenAPI 2.0 schema to OpenAPI 3.0.

What is your language?

I've found kin-openapi to be good for Go:

https://github.com/getkin/kin-openapi

I recently used https://github.com/getkin/kin-openapi openapi2 and openapi2conv to convert the v2 yaml to v3 yaml.

This might not be very helpful, but I've have found every "generate spec from code" package to be limited sooner or later, and that's across languages. I finally settled on writing the spec file by hand, linting it in CI using openapi-cli, and using kin-openapi in Go tests to ensure responses match their schema.

oklog/ulid to generate IDs. coreos/go-oidc for validating JWTs I get from auth. google/go-cmp for comparing structs in tests (unless the project is already using Testify). spf13/pflag because life's too short for Go's flag handling. getkin/kin-openapi for validating reqests/responses against my OpenAPI spec (in tests).

Then define the corresponding YAML/JSON specification (again manually) either using Swagger 2.0 (with go-swagger) or OpenAPI 3 (with kin-openapi), and

I'm already up to my elbows in AsciiDoc/Antora building a new online help platform, and I noticed that Swagger2Markup exists. No idea if it's any good, but I might be able to integrate it into my existing workflow and spit out some usable static content at the other end...

There are ways to generate a pdf from an OpenAPI-definition. You could use something like swagger2markup. But be warned that this approach has a pretty limited flexibility, the tools are often badly supported and it may involve a lot of work.