Error with buf generate when creating OpenAPI Spec from base YAML file with defined Auth settings

[devleejb]

When trying to create an OpenAPI Spec using buf generate from a base YAML file with defined Auth settings as shown below, the following error occurred:

Mar  5 12:21:11.299 ERR Failed to read input: oneOf constraint failed for SecuritySchemeOrReference with 0 valid results: map[Reference:required key missing: $ref SecurityScheme:oneOf constraint failed for SecurityScheme with 2 valid results: map[APIKey:required key missing: name MutualTLS:bad const value for "type" ("mutualTLS" expected, "http" received) Oauth2:required key missing: flows Oidc:required key missing: openIdConnectUrl]]
Failure: plugin connect-openapi: exit status 1
make: *** [proto] Error 1

My base YAML file:

openapi: 3.1.0
info:
  title: MyProject
  description: "My Project Description"
  version: v1.0.0
# 1) Define the security scheme type (HTTP bearer)
components:
  securitySchemes:
    bearerAuth: # arbitrary name for the security scheme
      type: http
      scheme: bearer
      bearerFormat: JWT # optional, arbitrary value for documentation purposes
# 2) Apply the security globally to all operations
security:
  - bearerAuth: [] # use the same name as above

[sudorandom]

@devleejb Thanks for this report! I've made a similar report to the openapi library that I'm using since the cause of the problem appears to be there: https://github.com/swaggest/openapi-go/issues/100.

[sudorandom]

That was quick! It looks like the problem is fixed upstream @devleejb! I updated openapi-go and made a new release: v0.5.3. Can you try upgrading and trying?

[devleejb]

@sudorandom Thank you for your quick fix!

But, after updating to v0.5.3, below error occurs.

Warning: Duplicate generated file name "yorkie/v1/yorkie.openapi.yaml". Buf will continue without error here and drop the second occurrence of this file, but please raise an issue with the maintainer of the plugin.
Warning: Duplicate generated file name "yorkie/v1/yorkie.openapi.yaml". Buf will continue without error here and drop the second occurrence of this file, but please raise an issue with the maintainer of the plugin.

It works well in v0.5.0.

[devleejb]

And these options doesn't work properly.

components:
  securitySchemes:
    basicAuth: # <-- arbitrary name for the security scheme
      type: http
      scheme: basic
security:
  - basicAuth: [] # <-- use the same name here

I'll comment it to swaggest/openapi-go!

https://github.com/swaggest/openapi-go/issues/100#issuecomment-1978574437

[sudorandom]

@devleejb oof. I fixed the "Duplicate generated file name" issue in v0.5.4.

[devleejb]

@sudorandom Awesome! Thank you very much! It works well!

[sudorandom]

I don't think I understand the issue you raised in swaggest/openapi-go. Are you seeing something wrong in the openapi output YAML now? Can you clarify here?

[devleejb]

@sudorandom

Below YAML file occurs error (basicAuth).

openapi: 3.1.0
info:
  title: MyProject
  description: "My Project Description"
  version: v1.0.0
components:
  securitySchemes:
    basicAuth: # <-- arbitrary name for the security scheme
      type: http
      scheme: basic
security:
  - basicAuth: [] # <-- use the same name here

[sudorandom]

I checked out the yorkie repo and applied the changes you discussed in your issue:

> cat api/docs/yorkie.base.yaml
openapi: 3.1.0
info:
  title: MyProject
  description: "My Project Description"
  version: v1.0.0
# 1) Define the security scheme type (HTTP bearer)
components:
  securitySchemes:
    bearerAuth: # arbitrary name for the security scheme
      type: http
      scheme: bearer
      bearerFormat: JWT # optional, arbitrary value for documentation purposes
# 2) Apply the security globally to all operations
security:
  - bearerAuth: [] # use the same name as above

and after calling buf generate with your given buf.gen.yaml file, I successfully get openapi output:

> grep -C10 bearerAuth api/docs/yorkie/v1/admin.openapi.yaml
        - 10
        - VALUE_TYPE_INTEGER_CNT
        - 11
        - VALUE_TYPE_LONG_CNT
        - 12
        - VALUE_TYPE_TREE
        - 13
      title: ValueType
      type: string
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http
security:
- bearerAuth: []
tags:
- description: Admin is a service that provides a API for Admin.
  name: yorkie.v1.AdminService

running your make docker-swagger command, this is what I see:

[sudorandom]

Oh, I see the difference now. You're doing basicAuth now. Sorry, I was just missed that detail!

[devleejb]

@sudorandom It's right. But, below base file doesn't run.

openapi: 3.1.0
info:
  title: MyProject
  description: "My Project Description"
  version: v1.0.0
components:
  securitySchemes:
    basicAuth: # <-- arbitrary name for the security scheme
      type: http
      scheme: basic
security:
  - basicAuth: [] # <-- use the same name here

The difference in this file is that it uses basicAuth instead of bearerAuth.

[sudorandom]

@devleejb in case you didn't see, I pushed a new version that includes the 2nd fix to openapi-go. 😄 Does it work fully? If you have different base openapi files for different protobuf files you may have to use gnostic annotations to configure specific paths: https://github.com/sudorandom/protoc-gen-connect-openapi/blob/main/gnostic.md (and you can use those annotations instead of having base.yaml altogether)

[devleejb]

@sudorandom It works well! Thank you for your help.

OK, I'll check the document.