Is it possible to have a PathItem.Parameter as a ref?

[Anthony-Bible]

Similar to #25, but in the reverse I want to be able to render to a ref:

paths:
  /test:
    get:
      operationId: getTest
      parameters:
        - $ref: '#/components/parameters/test' # This here

But it seems like the only potential option is possibly resolving the ref to the full yaml currently? The problem with this is we may use the ref in many places so that could increase our Openapi file by thousands of lines.

Just for a full picture, we're doing a protobuf to openapi spec and using this library to render the openapi:

This is the rpc:

  rpc GetUser(GetUserRequest) returns (User) {
    option (google.api.http) = {get: "/users"};
    option (google.api.method_signature) = "name";
    option (gnostic.openapi.v3.operation) = {
      description: "Get a user" // this will overwrite the comment above the rpc
      tags: "users" // this is used to group the operations in the gnostic.openapi spec, by default it only contains the service name
      operation_id: "GetUsers" // this by default is service_name + '_' + method_name

      // This refers to the header defined in the document option above, it will automatically document the header when converted to gnostic.openapi/json spec
      // it's currently commented out until our generation tool has support for it, once support is enabled we will uncomment this
      parameters: {reference: {_ref: "#/components/parameters/filter_mask"}}"#/components/parameters/filter_mask"
      };
}

We would like to render it like:

...
paths:
  /users:
    get:
      description: Get a User
      operation_id: GetUsers
      parameters:
        - $ref: "#/components/parameters/filter_mask"

The closest I can find is creating a proxy schema but that's only doing a ref for schemas so you'd still have lots of repeating lines.

[daveshanley]

Hi, I have tried reading through this - but I don't quite understand what it is you're trying to do.

[daveshanley]

Hi, I have taken some more time to understand this.

There is not currently the capability to do this when building up specs manually, What you;re looking for is a modification.

There are ways to do what you're looking for.

Option 1: Build the YAML structure manually

  // Create YAML nodes directly with $ref
  paramRefNode := &yaml.Node{
      Kind: yaml.MappingNode,
      Content: []*yaml.Node{
          {Kind: yaml.ScalarNode, Value: "$ref"},
          {Kind: yaml.ScalarNode, Value: "#/components/parameters/filter_mask"},
      },
  }

Option 2: Use a template approach

  // Build the OpenAPI as a template, then parse it
  spec := `
  openapi: 3.0.0
  paths:
    /users:
      get:
        parameters:
          - $ref: "#/components/parameters/filter_mask"
  components:
    parameters:
      filter_mask:
        name: filter
        in: query
        schema:
          type: string
  `
  doc, _ := libopenapi.NewDocument([]byte(spec))

But there is not a simple way to do this manually for Parameters. Schemas? no problem: https://pb33f.io/libopenapi/modifying/#using-references

This however is something that the library cannot yet do.

honestly I don't think I will be adding it myself, but I can leave this open for the community if they wish to implement it at some point.

We would need to add some kind of a builder API or something similar

  // A builder API that supports references (hypothetical)
  builder := openapi.NewBuilder()
  param := builder.DefineParameter("filter_mask", &Parameter{...})
  operation := builder.AddOperation("/users", "get")
  operation.AddParameterRef(param.GetReference())