read_only not working with references.

[SimonSikstrom]

So I want to be able to define messages in other messages as read_only fields when generating openapi doc, however, that does not seem possible at the moment.

Given example:

syntax = "proto3";

import "protoc-gen-swagger/options/annotations.proto";
import "google/api/annotations.proto";

service SomeService {
  // Create new Some
  rpc SomeService(SomeServiceRequest) returns (SomeMessage) {
    option (google.api.http) = {
      post: "/do-something"
      body: "body"
    };
  }
}

message SomeServiceRequest {
  SomeMessage body = 1;
}

message SomeMessage {
  // Readonly id, works fine here
  string id = 1 [(grpc.gateway.protoc_gen_swagger.options.openapiv2_field) = {read_only: true}];

  // OtherReadOnlyMessage readonly, does not work.
  OtherReadOnlyMessage field = 2 [(grpc.gateway.protoc_gen_swagger.options.openapiv2_field) = {read_only: true}];

  // OtherReadOnlyMessage not readonly
  OtherReadOnlyMessage other = 3;
}

// Message I want to use in multiple places
message OtherReadOnlyMessage {
  string whatever = 1;
}

It will output something like this:

{
  "swagger": "2.0",
  "info": {
    "title": "readonly.proto",
    "version": "version not set"
  },
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/do-something": {
      "post": {
        "summary": "Create A new Some",
        "operationId": "SomeService",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/SomeMessage"
            }
          },
          "default": {
            "description": "An unexpected error response",
            "schema": {
              "$ref": "#/definitions/runtimeError"
            }
          }
        },
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/SomeMessage"
            }
          }
        ],
        "tags": [
          "SomeService"
        ]
      }
    }
  },
  "definitions": {
    "OtherReadOnlyMessage": {
      "type": "object",
      "properties": {
        "whatever": {
          "type": "string"
        }
      },
      "title": "Message I want to use in two places"
    },
    "SomeMessage": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "title": "Readonly id, works",
          "readOnly": true
        },
        "field": {
          "$ref": "#/definitions/OtherReadOnlyMessage",
          "title": "OtherReadOnlyMessage readonly",
          "readOnly": true
        },
        "other": {
          "$ref": "#/definitions/OtherReadOnlyMessage",
          "title": "OtherReadOnlyMessage not readonly"
        }
      }
    },
...
  }
}

The readOnly field is set correctly but according to swagger docs:

Any sibling elements of a $ref are ignored. This is because $ref works by replacing itself and everything on its level with the definition it is pointing at.

• https://swagger.io/docs/specification/using-ref/

So its not reading and listing this property as read only in the end.

It seems like common practice is to instead of directly using $ref is to use allOf of the $ref instead, then the readOnly property would be used.

• https://stackoverflow.com/questions/51402156/how-to-declare-a-ref-property-as-readonly-in-openapi-swagger
• readOnly and writeOnly should be at the same level as required in the Schema OAI/OpenAPI-Specification#1671
• OAS 3.0: readOnly properties are included in request body examples swagger-api/swagger-ui#3445 (comment)

So this

...
"field": {
          "$ref": "#/definitions/OtherReadOnlyMessage",
          "title": "OtherReadOnlyMessage readonly",
          "readOnly": true
        },
...

Should in that case become this:

...
        "field": {
          "title": "OtherReadOnlyMessage readonly",
          "readOnly": true,
          "allOf": [
            { "$ref": "#/definitions/OtherReadOnlyMessage" }
          ]
        },
...

Thoughts?

[johanbrandhorst]

Hey @SimonSikstrom, thanks for the detailed issue report! Your analysis sounds reasonable, and also your proposed solution. Would you be interested in contributing this fix?

[SimonSikstrom]

Thanks for the quick response! Sure I could have a look and see if this is something I could solve in a reasonable timeframe. I'll link upcoming PR if I have something ready.