support loading openapi specification files from git repos

[jxsl13]

allow fetching individual files from git repos ssh + https + local file + plain https w/o git

• local files
• plain http/s where the response contains the api spec
• git/https where you need to checkout a single commit in memory in order to open the file
• git/ssh (same as above)

supported schema formats

# local files (relative and absolute paths)
../../examples/petstore-expanded/petstore-expanded.yaml
file://../../examples/petstore-expanded/petstore-expanded.yaml

# https

https://raw.githubusercontent.com/deepmap/oapi-codegen/master/examples/petstore-expanded/petstore-expanded.yaml

# git/https

https://github.com/deepmap/oapi-codegen.git/examples/petstore-expanded/petstore-expanded.yaml
# with additional branch specification
https://github.com/deepmap/oapi-codegen.git/examples/petstore-expanded/petstore-expanded.yaml@master

# git/ssh

[email protected]:22:deepmap/oapi-codegen.git/examples/petstore-expanded/petstore-expanded.yaml
[email protected]:22:deepmap/oapi-codegen.git/examples/petstore-expanded/petstore-expanded.yaml@master

[email protected]:deepmap/oapi-codegen.git/examples/petstore-expanded/petstore-expanded.yaml
[email protected]:deepmap/oapi-codegen.git/examples/petstore-expanded/petstore-expanded.yaml@master

ssh://[email protected]:22:deepmap/oapi-codegen.git/examples/petstore-expanded/petstore-expanded.yaml
ssh://[email protected]:22:deepmap/oapi-codegen.git/examples/petstore-expanded/petstore-expanded.yaml@master

ssh://[email protected]:deepmap/oapi-codegen.git/examples/petstore-expanded/petstore-expanded.yaml
ssh://[email protected]:deepmap/oapi-codegen.git/examples/petstore-expanded/petstore-expanded.yaml@master

Our use case:

Currently we manage the api specs, generated types as well as the echo server boilerplate in a single repository/go module. When using the central module, we always get the echo dependency even tho we might not want to implement a server side application but a client application which does not require the echo stuff. Another aspect is that we want to have a single source of truth for our openapi specs and not copy those around.

With this extension it is possible to create three repos, one for the openapi spec, one for clients which only contain types. We will not need to create a server boilerplate outside of our server applications anymore, which might be pretty nice.

Thinking further, it might be possible to have a single source of truth for api spec, client and types which is used by the server generator with an import mapping configuration.

[deepmap-marcinr]

Regarding your first question - that you only want the models, that's pretty easy, just select models as your only output, and you will only get the data types, no Echo, no ServerInterface, etc.

As for pulling from git, I'm not sure how I feel about that. It's one of these complications that makes usage nicer, but it's not really necessary. For example, we use Makefiles to put specs into a build directory, and they can be obtained via wget. I realize that's our workflow.

We need to fix models to be importable in a separate package. It's doable right now with a . alias import, but it would be nice to be explicit.

[jxsl13]

@deepmap-marcinr could you provide an example. We want to have the openapi spec in a single location which is usually a private git repo. We don't want to have any copy of the openapi spec in any other repository other than the one location (single source of truth with revisions)

One Go module should contain the types and optionally client implementations. In dedicated backend apis we'd like to also not have any manually copied openapi specs but still be able to generate the server boilerplate.

In the best case the client and server would share the exact same models and not redundantly generated models.

With this extension it might be possible to write git urls in go generate magic comments and you'd have skipped some e.g. Jenkins pipeline/Makefile step where you need to fiddle out a single openapi spec from a git repo.

PS: could you take a look at this completed PR: https://github.com/deepmap/oapi-codegen/pull/674