operation-summary-sentence-case

Operation summary uses sentence casing

Authors:

• @TaylorKrusen Taylor Krusen (Redocly)

What this does and why

What -- this rule enforces a consistent pattern of capitalization on Operation summaries.

Why -- "Sentence casing vs title casing" may be the "tabs vs spaces" of the writing world, but being consistent is often more important than being right. At Redocly, we prefer sentence casing for Operation summaries. By adding this configurable rule to our linter, we ensure our entire team writes them that way.

Code

Here's how the configurable rule looks in the redocly.yaml file:

rules:
  rule/operation-summary-sentence-case:
    subject:
      type: Operation
      property: summary
    message: "Operation summary must be sentence cased."
    assertions:
      pattern: /^[A-Z]+[^A-Z]+$/

Note

This rule can be repurposed for other fields with a single sentence, but not multiple sentences.

Rule explanation

This rule asserts that each Operation summary matches the regex defined in pattern. The regex we defined matches strings that:

1. Start with an uppercase letter
2. Are followed by 1+ characters that are not uppercase letters
3. End with a character that is not an uppercase letter

Tip: Building a regex for your own rule? A tool like regexr can be quite useful.

Examples

Summaries with sentence casing (correct):

/orders:
  post:
    summary: Create order
/orders/{orderId}:
  get:
    summary: Retrieve an order

Summaries without sentence casing (incorrect):

/orders:
  post:
    summary: Create New Order
/orders/{orderId}:
  get:
    summary: retrieve an Order

Excluding operations from the rule

Sometimes you might need an exception to the rule. For example, your Operation summary could have a proper noun or an acronym. You can do that using an ignore file.

Example - ignoring sentence casing

Pretend you have the following Operation and want to keep "OAuth2" capitalized in the summary:

/oauth2/register:
  post:
    summary: Create OAuth2 client

1. Verify your sentence casing rule is working correctly

• Run npx @redocly/cli lint
• Console should show error on Operation summary

The linting output from our example:

Operation summary must be sentence cased.

 6 | /oauth2/register:
 7 |   post:
 8 |     summary: Create OAuth2 client
 9 |     description: Register a new OAuth2 client for dynamic client registration.
10 |     operationId: registerOAuth2Client

Error was generated by the rule/operation-summary-sentence-case rule.

2. Generate an ignore file

• Run npx @redocly/cli lint --generate-ignore-file
• Console should confirm an ignore file was generated
• A .redocly.lint-ignore.yaml was added to your code

The ignore file generated by our example:

# .redocly.lint-ignore.yaml
openapi.yaml:
  rule/operation-summary-sentence-case:
    - '#/paths/~1oauth2~1register/post/summary'

3. Run the linter and verify your Operation summary is ignored

• Run npx @redocly/cli lint
• Console output should confirm valid OpenAPI description

The linting output from our example with ignore file added:

Woohoo! Your API description is valid. 🎉
1 problem is explicitly ignored.