[REQ] Better Structure for Go Server Project

[zhoub]

Is your feature request related to a problem? Please describe.

Hi,

Now the go-server creates a project like this

│   main.go
│   Dockerfile
│   .openapi-generator-ignore
│
├───go
│       model_user.go
│       api_default.go
│       routers.go
│       logger.go
│       README.md
│
├───api
│       openapi.yaml
│
└───.openapi-generator
        VERSION

Describe the solution you'd like

Shall we create a structure similar to the go-swagger generates folders.

cmd/<server's name>/main.go
models/<all models>

Thanks !

[wing328]

@zhoub thanks for the suggestion. I'm definitely not against that.

The current project structure is very similar to the one in Go Gin: https://github.com/OpenAPITools/openapi-generator/tree/master/samples/server/petstore/go-gin-api-server

My take is to adopt one or the other but not both.

For go-swagger project structure, what's the advantage?

[mpreu]

@wing328
I would like to see a better (or maybe more flexible) project structure in the generated go-projects as well. Right now it is very difficult to incorporate the generated code in a project when not totally relying on the whole generated code (interface-only preferred, see #426). Usually I have to workaround that with post-processing like moving files (or deleting unnecessary, etc).

For what it's worth I have the following suggestions:

1. Adaptation of a much more common repository structure to reflect best-practices if possible

Hereby I refer to this go project structure guidelines: https://github.com/golang-standards/project-layout. It is an unofficial set of guidelines, but is adopted by a lot of the biggest go-projects. For example:

• https://github.com/docker/cli
• https://github.com/kubernetes/kubernetes
• https://github.com/openshift/origin
  (list continues)

In its basic form the guidelines are about separating:

• ./cmd/... for the different executables. Here are almost always simple main.go files
  (used by the go tools https://github.com/golang/tools/tree/master/cmd)
• ./internal/... for the internal, non-public library code in the project
  (go standard and supported by the tooling https://golang.org/doc/go1.4#internalpackages)
• ./pkg/... for the public library code in the project
  (discussable pkg directory should not be recommended for use golang-standards/project-layout#10, should not be enforced)

The https://github.com/golang-standards/project-layout already lists some citations, but I would like to add:

• https://peter.bourgon.org/go-best-practices-2016/#repository-structure
• https://medium.com/@benbjohnson/standard-package-layout-7cdbc8391fc1

Of course, for each project which complies with this unofficial guidelines you can find an unlimited amount of projects doing it in another way. But from my experience a lot of projects with more relevance have these guidelines incorporated, at least they are respecting the 'cmd' / 'internal' folder structure. The single source folder and single package structure, which is generated right now in the go-generators can be considered as an anti-pattern (see also https://blog.golang.org/package-names, section 'Don't use a single package for all your APIs').

2. With the changed folder structure it is, in my opinion, much more convenient to address problems like [REQ] [go-gin-server] place models in different package to prevent circular package references  #2752 or [REQ] A way to specify for generated code destination package #2681 . Different packages can then live in a more "standard" import path in the repository and the overall code separation should be better.

3. Regarding the flexibility: The configuration-file should be able to handle different options to not enforce a specific project structure policy, like:

• Path for generated models -> e.g. "./pkg/generatedModels/...
• Path for generated apis -> e.g "./internal/generatedApis/...

At least point 3. should be considered (in a more detailed way of course). Right now the flexibility is to define where the overall output folder or the generated "go" source code folder should be in the repository. To adapt the generated code to your project, incorporate a more common folder structure or respect go best practices, post-processing via scripting is required right now.