sasswart/can

Generate Go gin servers from OpenAPI specs

can's Issues

Feature: Proper windows path compatibility

We're currently wrapping paths in filepath.Clean() in the hopes that the filepath package will handle a lot of the os-specific path formatting. This isn't thoroughly tested and we should adopt the community best practice on how this should be done.

Only include fmt and regexp in the generated models package when it's needed

This config will produce a broken models package:

openapi: 3.0.0
paths:
  /heartbeat:
    get:
      responses:
        200:
          description: "Serves the API's documentation"
          content:
            "application/json":
              schema: {}
info: {}

Allow for openapi files to be accepted with `.yaml` extensions

We currently only accept .yml files.

Interfaces generated for multiple paths clutter up `Server{}` interface

Consider grouping multiple function signatures into their own path-named interface. This will allow the Server interface to remain uncluttered as it can be composed by-endpoint as opposed to including every signature definition.

Current

type Server interface {
  DomainDelete(*gin.Context, *models.DomainDeleteRequest) models.DomainDeleteResponse
  DomainGet(*gin.Context, *models.DomainGetRequest) models.DomainGetResponse
  DomainPatch(*gin.Context, *models.DomainPatchRequest) models.DomainPatchResponse
  DomainPost(*gin.Context, *models.DomainPostRequest) models.DomainPostResponse
  ProjectDelete(*gin.Context, *models.ProjectDeleteRequest) models.ProjectDeleteResponse
  ProjectGet(*gin.Context, *models.ProjectGetRequest) models.ProjectGetResponse
  ProjectPatch(*gin.Context, *models.ProjectPatchRequest) models.ProjectPatchResponse
  ProjectPost(*gin.Context, *models.ProjectPostRequest) models.ProjectPostResponse
  ProjectListGet(*gin.Context, *models.ProjectListGetRequest) models.ProjectListGetResponse
}

For improved organization

type Server interface {
  DomainInterface
  ProjectInterface
}

Feature: CLI rest client generation

Generate and compile a binary from go code that will allow for an easy interface with any server created by can. This could be done in golang through the use of cobra-cli

Response Type and GetStatus() method not generated for 204 response definitions

We don't currently generate the Response Type and GetStatus() method for a 204 no content responses. This breaks code that requires the 204 response to be checked and currently fundamentally breaks this functionality

Feature: OAuth2 Authentication

Currently unsupported and would improve our coverage of the OpenApi specification if we were to support it.

Bundle templates in release archive and be able to specify which template directory to use in the config file

Without this, the entire gin-in-a-can repository must be cloned for it to be useful.

Update go-gin templates to check for the absence of required attributes during input validations

Always include a Response model for unimplemented requests, defined by config value

We generate a base Struct that represents an unimplemented server from which a concrete server can be composed.
This unimplemented server currently returns the status code defined by InvalidRequestStatus in the config file.

This should change to a config option called UnimplementedResponseCode and a model should always be generated for it for every request.

Clean underscores from generated function names in go-gin server template

Function names are informed by the content in the make file. A path of items/:item_id/thing currently produces function names that substitute out the colon for an additional underscore and accept the underscore present in the path parameter. This breaks go function name guidelines.

Decouple the generator from knowing what an OpenAPI file is.

OpenAPI files are read and parsed in the openapi package.
The generator should not know about them.

The generator knows how to take its data and put it down as a template.

Sort generated code as to avoid random redistribution of resultant code over successive generation steps

Quality of life improvement.
This will allow for the common pieces of successive generations to remain in similar places, making diffs easier to read over incremental changes to source files

Feature: TypeScript API client generation

Allow config file location to be specified using a cli tag

This is necessary in order to be able to integrate gin-in-a-can into ci pipelines where the config file might be part of a different repo in a different directory.

Release with default configuration file

This would allow the application to be plug and play for most applications that fit it's initial use case.
Alternatively one could hardcode the config file and allow for a template to be sent to stdout for capture by the user intending to set their own config to feed in via the intended CLI flag

go-client: Required Tag for property does not function correctly

                  domains:
                    type: array
                    required: [domain]
                    items:
                      type: object
                      required: [name, enabled]
                      properties:
                        explicit_domain_id:
                          type: string
                        id:
                          type: string
                        name:
                          type: string
                        description:
                          type: string
                        enabled:
                          type: boolean

An open api definition such as this does not cause the generated code to omit the omitempty json tag for the domain, name, and enabled fields in the generated structs.

Formalise Name Inference rules for models

Schemas do not have names in the OpenAPI Spec.
Model objects in code need names.

Name inference therefore needs to be a thing.
The most obvious name inference rule is to sanitise $refs into model names.
Unfortunately, they are not always available.