[protoc-gen-openapi] Document Option Support Wonkeyness

[jeffsawatzky]

With the new options that were added in #324 I have come across either some weird bug somewhere...or more likely a usage error on my part, but I can't figure out what exactly the usage error is.

For instance, if I have a proto file with the following content:

syntax = "proto3";

package api.v20190710;

import "openapiv3/annotations.proto";

option (openapi.v3.document) = {
  info: {
    title: "My Title";
    version: "2019-07-10";
    description: "Public API for Automating Stuff";
    contact: {
      name: "API Contact";
      url: "https://www.example.com/api/start";
      email: "contact@example.com";
    }
    license: {
      name: "MIT";
      url: "https://github.com/git/git-scm.com/blob/main/MIT-LICENSE.txt";
    }
  }
  components: {
    security_schemes: {
      additional_properties: [{
        name: "OAuth2";
        value: {
          security_scheme: {
            type: "oauth2";
            description: "For more information see [documentation](https://www.example.com/api/authentication)";
            flows: {
              authorization_code: {
                authorization_url: "https://auth.example.com/oauth/authorize";
                token_url: "https://api.example.com/auth/oauth/token";
                refresh_url: "https://api.example.com/auth/oauth/token";
                scopes: {
                  additional_properties: [{
                    name: "user:resource:read";
                    value: "Read resource";
                  },
                  {
                    name: "user:resource:write";
                    value: "Write resource";
                  }]
                }
              }
            }
          }
        }
      }]
    }
  }
};

The resulting openapi.yaml file I get looks like:

# Generated with protoc-gen-openapi
# https://github.com/google/gnostic/tree/master/cmd/protoc-gen-openapi

openapi: 3.0.3
info:
    title: My Title
    description: Public API for Automating Stuff
    contact:
        name: API Contact
        url: https://www.example.com/api/start
        email: contact@example.com
    license:
        name: MIT
        url: https://github.com/git/git-scm.com/blob/main/MIT-LICENSE.txt
    version: "2019-07-10"
components:
    securitySchemes:
        OAuth2:
            type: oauth2
            description: For more information see [documentation](https://www.example.com/api/authentication)
            flows:
                authorizationCode:
                    authorizationUrl: https://auth.example.com/oauth/authorize
                    tokenUrl: https://api.example.com/auth/oauth/token
                    refreshUrl: https://api.example.com/auth/oauth/token
                    scopes: {}

Which looks correct for the most part, except for the scopes way down in the components.securitySchemes.OAuth2.flows.authorizationCode which is missing the scopes, and I can't seem to figure out why.

Looking at the OpenAPIv3.proto:

1. scopes is a Strings message type
2. Strings has a repeated NamedString called additional_properties
3. NamedString has string name and value properties

So as far as I can tell I am constructing the options correctly following the protos.

@timburks / @morphar am I missing something? Why aren't the scopes getting output? Please point out my mistake.

[morphar]

That's a really good question! Out of the top of my head, I can't even start to guess...
I would need to dig into the code to start guessing.

[jeffsawatzky]

I'll try to take a look when I have time. Last week I was taking some "innovation" time so I had a bit more free time to do things. Now I'm back to having less time to look into things like this.

[timburks]

The problem is here - the ToRawInfo() for Strings is unimplemented. This is generated code, so I'll fix the generator. Here is the code that I think should be there:

       if m.AdditionalProperties != nil {
               for _, item := range m.AdditionalProperties {
                       info.Content = append(info.Content, compiler.NewScalarNodeForString(item.Name))
                       info.Content = append(info.Content, compiler.NewScalarNodeForString(item.Value))
               }
        }

When I add that manually, the scopes are exported correctly. Thanks for catching this :)

[timburks]

Looks fixed by #333. Looking at the result, I'm wondering if YAML parsers are usually smart enough to handle ':' embedded in keys like you have here:

                    scopes:
                        user:resource:read: Read resource
                        user:resource:write: Write resource

But fortunately gnostic (yaml.v3) reads it with no problems!

% gnostic openapi.yaml --yaml-out=-
openapi: 3.0.3
...
components:
    schemas: {}
    securitySchemes:
        OAuth2:
            type: oauth2
            description: For more information see [documentation](https://www.example.com/api/authentication)
            flows:
                authorizationCode:
                    authorizationUrl: https://auth.example.com/oauth/authorize
                    tokenUrl: https://api.example.com/auth/oauth/token
                    refreshUrl: https://api.example.com/auth/oauth/token
                    scopes:
                        user:resource:read: Read resource
                        user:resource:write: Write resource

[timburks]

@jeffsawatzky please close if you find this is fixed now.

[jeffsawatzky]

Fixed! Thank you so much!