search

OpenAPITools / openapi-generator

OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)
https://openapi-generator.tech
Apache License 2.0
21.37k stars 6.46k forks source link

[REQ] Better Structure for Go Server Project #1931

Open zhoub opened 5 years ago

zhoub commented 5 years ago

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 commented 5 years ago

@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 commented 5 years ago

@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:

In its basic form the guidelines are about separating:

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

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').

  1. With the changed folder structure it is, in my opinion, much more convenient to address problems like #2752 or #2681 . Different packages can then live in a more "standard" import path in the repository and the overall code separation should be better.

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

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.