google / google/gnostic

OpenAPIv3Generator does not remove multiline linter comments from generated yaml.

Open
#462 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
Go
Stars
2.3k
Forks
279
PR merge metrics
No merged PRs in 30d

Description

Multiline linter comments in the proto (those delimited with `(--` and `--)`) are not correctly removed from generated yaml.

As a canonical example of why this is necessary, consider [AIP-200](https://google.aip.dev/200), which states:

> If an API violates the AIP standards for any reason, there must be an internal comment linking to ([aip.dev/not-precedent](https://google.aip.dev/200)) to ensure others do not copy the violations or cite the errors as precedent of a "previously approved API".
> The comment should also include an explanation of what violates standards and why it is necessary.

The example given of how to format this comment is:

```proto
message DailyMaintenanceWindow {
// Time within the maintenance window to start the maintenance operations.
// It must use the format "HH MM", where HH : [00-23] and MM : [00-59] GMT.
// (-- aip.dev/not-precedent: This was designed for consistency with crontab,
// and preceded the AIP standards.
// Ordinarily, this type should be `google.type.TimeOfDay`. --)
```

Which can be combined with other linter patterns.

Note that this comment is split over multiple lines.

Since these comments are required to follow AIP standards, OpenAPIv3Generator should support removing them as well, but it cannot since `OpenAPIv3Generator.linterRulePattern` is set to `\(-- .* --\)`, which will not account for newlines.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.