Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Description and title ignored when field is not a scaler value type #892

Closed
PassKit opened this issue Mar 4, 2019 · 1 comment
Closed

Comments

@PassKit
Copy link

PassKit commented Mar 4, 2019

When adding descriptions or titles for message fields that are not scaler value types, any title or description option is ignored, and replaced (if available) with the description of the message type.

This prevents proper context being provided for reusable items.

As an example, we have a date message that is re-used in multiple places.

// A fixed date without timezone information.
message Date {
    // Year.
    int32 year = 1;
    // Month.
    int32 month = 2;
    // Date.
    int32 day = 3;
}

And in the following message, a description is added to add context to the date value required:

// Details of document used to identify the traveler's identity.
message IdentityDetails {
    IdentityDocument identityDocument = 1;
    // The two digit ISO 3166 country code of the country of the travel document issuing authority.
    string issuingCountry = 2;
    // The two digit ISO 3166 country code of the traveler's nationality.
    string nationality = 3;
    // The number or other unique identifying reference of the traveler's document.
    string documentNumber = 4;
    // The date of birth as marked on the traveler's identity document.
    Date dateOfBirth = 5;
    // The gender as marked on the traveler's identity document.
    Gender gender = 6;
    // The issue date of the traveler's identity document.
    Date issuedDate = 7;
    // The expiry date of the traveler's identity document.
    Date expiryDate = 8 [(grpc.gateway.protoc_gen_swagger.options.openapiv2_field) = {title: "Nothing to see here", description: "The expiry date of the traveler's identity document."}];
}

But both the short-form comments, or the long form options are ignored when the JSON is generated:

    "boardingIdentityDetails": {
      "type": "object",
      "properties": {
        "identityDocument": {
          "$ref": "#/definitions/boardingIdentityDocument"
        },
        "issuingCountry": {
          "type": "string",
          "description": "The two digit ISO 3166 country code of the country of the travel document issuing authority."
        },
        "nationality": {
          "type": "string",
          "description": "The two digit ISO 3166 country code of the traveler's nationality."
        },
        "documentNumber": {
          "type": "string",
          "description": "The number or other unique identifying reference of the traveler's document."
        },
        "dateOfBirth": {
          "$ref": "#/definitions/ioDate",
          "description": "The date of birth as marked on the traveler's identity document."
        },
        "gender": {
          "$ref": "#/definitions/ioGender",
          "description": "The gender as marked on the traveler's identity document."
        },
        "issuedDate": {
          "$ref": "#/definitions/ioDate",
          "description": "The issue date of the traveler's identity document."
        },
        "expiryDate": {
          "$ref": "#/definitions/ioDate",
          "description": "The expiry date of the traveler's identity document."
        }
      },
      "description": "Details of document used to identify the traveler's identity."
    }

I believe there should be a hierarchy of annotations, making it possible to override the referenced object description.

@PassKit PassKit closed this as completed Mar 4, 2019
@PassKit
Copy link
Author

PassKit commented Mar 4, 2019

Please ignore. protocol-gen-swagger is working as expected. My issue is with the ReDoc project.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

0 participants