[Go] Optional values should be pointers

[langston-barrett]

Description

If a field of a struct isn't specified as required, then it should be a pointer to that value so that one can differentiate between unset by the user or set to the "zero value". See the following Go playground: https://play.golang.org/p/85r_JbH5XVr

See also e.g. this Stackoverflow answer.

openapi-generator version

Docker container

OpenAPI declaration file content or url

---
openapi: 3.0.0
info:
  title: unset
  version: 0.1.0

paths:
  "/foo":
    get:
      summary: foo
      responses:
        '200':
          description: OK
          content:
            application/xml:
              schema:
                "$ref": "#/components/schemas/Bar"

components:
  schemas:
    Bar:
      properties:
        X:
          type: integer
        Y:
          type: integer
      required:
        - X

Related issues/PRs

Suggest a fix/enhancement

[langston-barrett]

Would this be as simple to fix as changing a single line of a template?

[grokify]

This would be a good update.

It may be as simple as changing the model template. If so, you can just update it, rebuild the CLI and run it against your spec to see if it works.

The template is here:

https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator/src/main/resources/go/model.mustache

Here are some steps to do this. For the example, I've assumed you have a fork and want to send a PR ;)

$ git clone https://github.com/siddharthist/openapi-generator
$ cd openapi-generator
$ git checkout -b go/client/fix/optional-as-pointer
$ vi modules/openapi-generator/src/main/resources/go/model.mustache
$ mvn clean package
$ java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar help

Use the resulting openapi-generator-cli.jar to rebuild your client and see if it works as expected.

If so, then do the following to send a PR with the following:

$ bin/go-petstore.sh
$ mvn verify -f samples/client/petstore/go
$ mvn verify
$ git add
$ git commit -m 'use pointers for optional properties'
$ bin/util/ensure-up-to-date
$ git push origin go/client/fix/optional-as-pointer

If this is not in the petstore sample app, you can look into updating the sample Petshop Swagger 2.0 spec listed in bin/go-petstore.sh so your change is reflected in the generated go-petstore sample client.

If ensure-up-to-date creates new files or tells you to update your code, do it and run it again. Rinse and repeat until it says your working tree is clean.

Even if you edit only the model.mustache file, this may result in more files b/c you are rebuilding the Petstore sample and ensure-up-to-date may have you update other samples.

Then push to your fork and send a PR.

[langston-barrett]

@grokify Wow, thank you for the thorough instructions! I hope you have this saved as a "quick reply" 😄 I'd like to solve this, I'll report back here (within a week) if I'm able to.

[langston-barrett]

The fix is indeed one line. I have a branch here: https://github.com/siddharthist/openapi-generator/tree/go/client/fix/optional-as-pointer. I tested this with my project and it works fine.

Unfortunately, it looks like it will take more effort than I can justify to fix the tests: many of the fields are optional and now must be converted to pointers. Example conversion in my branch.

[grokify]

@siddharthist Thanks for looking into this.

There aren't actually that many tests so it should be reasonably easy to update. The tests are located here:

samples/client/petstore/go/auth_test.go
samples/client/petstore/go/fake_api_test.go
samples/client/petstore/go/pet_api_test.go
samples/client/petstore/go/store_api_test.go
samples/client/petstore/go/user_api_test.go

[grokify]

@siddharthist I just put together a contribution quickstart here:

https://medium.com/ringcentral-developers/openapi-generator-for-go-contribution-quickstart-8cc72bf37b53

Take a look. I'll also take a look at your change when I have time.

[antihax]

Was this not resolved with the optional package?
It may be better to extend that, since we could have NULL as a valid value in addition to NotSet?

[mattes]

I noticed the generated Go package uses github.com/antihax/optional for optional fields. This requires me to pass in a string with optional.NewString("foobar"). Example:

import "github.com/antihax/optional"

type UpdatePetWithFormOpts struct {
	Name optional.String
	Status optional.String
}

s := UpdatePetWithFormOpts{
	Name: optional.NewString("foobar"),
}

I found Google's approach more intuitive. They define a string as an interface{}, which allows something like this:

import "google.golang.org/cloud/internal/optional"

type UpdatePetWithFormOpts struct {
	Name optional.String
	Status optional.String
}

s := UpdatePetWithFormOpts{
	Name: "foobar",
	Status: nil,
}

[antihax]

You lose compile time type checking by using interface{}.

The Google library there will panic at runtime if a wrong type is passed, which is a bad way to handle this.

[bkabrda]

So I've just hit this issue and have a couple of observations:

• This problem was not solved by using the optional package, as it is only used for Opts, not for Models.
• Even if it was used for Models, I think it would need to provide means for json (un)marshalling - if I'm not mistaken, this is something that's not possible ATM.
• Even if we did use optional for Models and it had support for json (un)marshalling, we'd still need to have a mechanism for nested references, i.e. the case when structure contains attribute that references a different structure - AFAICS this wouldn't be supported by optional right now (basically I think we'd need to use pointers for struct types).

If the 3 above points seem correct, I'd be happy to work on them; CC @antihax.

[wing328]

cc @antihax (2017/11) @bvwells (2017/12) @grokify (2018/07) @kemokemo (2018/09)