LukeParke/redocly-cli
1
0
Fork 0
mirror of https://github.com/LukeHagar/redocly-cli.git synced 2025-12-06 04:21:09 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
909fb471ca01e26855e2802be8e891acb41962ae
redocly-cli/docs/rules/path-segment-plural.md
Lorna Jane Mitchell 909fb471ca Add Vale for prose linting (#1099) 
* feat: Add Vale configuration and rules

* docs: Fix top-level files to match Vale rules

* docs: Vale updates for the commands docs

* docs: apply Vale updates to the decorator docs

* docs: Update guides to match Vale rules

* docs: update rules and other content to meet Vale standards

* docs: add Vale link and information to CONTRIBUTING

* feat: Add GitHub action for Vale

* docs: minor editing to readme.md

* docs: minor editing to the changelog.md file

* docs: minor edits to the join.md file in commands folder

* docs: minor edits to lint.md file in the commands directory

* docs: minor edit to the login.md file in the commands directory

* docs: minor edits to the preview.md file in the commands directory

* docs: minor edits to push.md file in the comands directory

* docs: minor edits to the info-description-override.md file in the decorators directory

* docs: minor edits to the configure-rules.md file in the guides directory

* docs: minor edits to custom-plugin.md file in the resources directory

* docs: minor editing to the no-http-verbs-in-paths.md file in the rules directory

---------

Co-authored-by: Heather Cloward <heathercloward@gmail.com>
2023-06-01 10:10:43 +01:00

2.0 KiB
Raw Blame History

path-segment-plural

Enforces plural path segments.

OAS Compatibility
2.0 ✅
3.0 ✅
3.1 ✅

API design principles

RESTful API design often uses resources in path segments and those resources are typically plural.

For example, "customers" instead of "customer" because:

  • GET /customers means getting a collection of customers
  • GET /customers/abc means getting customer ABC from the customers collection

As your API grows, you may hit some false positives and may also need to ignore a few outliers. That is, unless you're a purist. Nothing wrong with that.

Configuration

Option Type Description
severity string Possible values: off, warn, error. Default off (in recommended configuration).
ignoreLastPathSegment boolean Ignores the last path segment if true. Default value: false.
exceptions [string] List of strings to exclude when checking path segments, for example, v1.

An example configuration:

rules:
  path-segment-plural: error

Another example configuration:

rules:
  path-segment-plural:
    severity: error
    ignoreLastPathSegment: true
    exceptions:
      - v1
      - v2
      - people

Examples

Given this configuration:

rules:
  path-segment-plural: error

Example of an incorrect path segment:

paths:
  /customer/{id}:
    post:
      parameters:
        - name: id
          in: path
          required: true

Example of a correct path segment:

paths:
  /customers/{id}:
    post:
      parameters:
        - name: id
          in: path
          required: true
          description: The customer's ID.

Related rules

Resources