Skip to content

Latest commit

 

History

History
 
 

paths

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
README.md
README.md
 
 
api@curriculum@usage@{id}.yaml
api@curriculum@usage@{id}.yaml
 
 
api@register@{provider}.yaml
api@register@{provider}.yaml
 
 
[email protected]
[email protected]
 
 
api@user@{id}@notify.yaml
api@user@{id}@notify.yaml
 
 
assessment.yaml
assessment.yaml
 
 
assessment@{id}.yaml
assessment@{id}.yaml
 
 
calendar@event@attendance@{id}.yaml
calendar@event@attendance@{id}.yaml
 
 
calendar@event@attendance@{id}@accept.yaml
calendar@event@attendance@{id}@accept.yaml
 
 
calendar@event@attendance@{id}@create.yaml
calendar@event@attendance@{id}@create.yaml
 
 
calendar@event@attendance@{id}@decline.yaml
calendar@event@attendance@{id}@decline.yaml
 
 
calendar@event@attendance@{id}@delete.yaml
calendar@event@attendance@{id}@delete.yaml
 
 
discussion@{contextType}@{contextId}@comments@{id}.yaml
discussion@{contextType}@{contextId}@comments@{id}.yaml
 
 
discussion@{contextType}@{contextId}@comments@{id}@comments.yaml
discussion@{contextType}@{contextId}@comments@{id}@comments.yaml
 
 
discussion@{contextType}@{contextId}@threads.yaml
discussion@{contextType}@{contextId}@threads.yaml
 
 
discussion@{contextType}@{contextId}@threads@{id}.yaml
discussion@{contextType}@{contextId}@threads@{id}.yaml
 
 
discussion@{contextType}@{contextId}@threads@{id}@close.yaml
discussion@{contextType}@{contextId}@threads@{id}@close.yaml
 
 
discussion@{contextType}@{contextId}@threads@{id}@comments.yaml
discussion@{contextType}@{contextId}@threads@{id}@comments.yaml
 
 
discussion@{contextType}@{contextId}@threads@{id}@open.yaml
discussion@{contextType}@{contextId}@threads@{id}@open.yaml
 
 
evidence@user@{id}@create.yaml
evidence@user@{id}@create.yaml
 
 
evidence@{id}.yaml
evidence@{id}.yaml
 
 
evidenceFeed@user@{id}.yaml
evidenceFeed@user@{id}.yaml
 
 
[email protected]
[email protected]
 
 
news@feed@{key}.yaml
news@feed@{key}.yaml
 
 
news@[email protected]
news@[email protected]
 
 
news@lists@folder@{id}.yaml
news@lists@folder@{id}.yaml
 
 
news@[email protected]
news@[email protected]
 
 
news@moderation@{id}@{status}.yaml
news@moderation@{id}@{status}.yaml
 
 
[email protected]
[email protected]
 
 
news@saved@{id}@add.yaml
news@saved@{id}@add.yaml
 
 
news@saved@{id}@remove.yaml
news@saved@{id}@remove.yaml
 
 
[email protected]
[email protected]
 
 
news@{id}.yaml
news@{id}.yaml
 
 
news@{id}@delete.yaml
news@{id}@delete.yaml
 
 
pastoral@[email protected]
pastoral@[email protected]
 
 
resource@file@{fileId}@ajax.yaml
resource@file@{fileId}@ajax.yaml
 
 
[email protected]
[email protected]
 
 
user.yaml
user.yaml
 
 
[email protected]
[email protected]
 
 
user@token@{id}.yaml
user@token@{id}.yaml
 
 
user@{id}.yaml
user@{id}.yaml
 
 
user@{id}@groupMembership.yaml
user@{id}@groupMembership.yaml
 
 
user@{id}@groupMembership@{groupId}.yaml
user@{id}@groupMembership@{groupId}.yaml
 
 

README.md

Paths

Organize your path definitions within this folder. You will reference your paths from your main openapi.yaml entrypoint file.

We have adopted these conventions:

  • path separator token (@) or subfolders
  • path parameter (e.g. {example})
    • note that paths are in
  • each path in a separate file, instead of each operation in a separate file

Each path in a separate file

Use the predefined "path separator" and keep all of your path files in the top level of the paths folder.

user.yaml      # /user paths, i.e. GET to search for users, POST to create user 
user@{id}.yaml # /user/{id} paths, i.e. PUT to update, DELETE to delete

Motivations

  • Quickly see a list of all paths. Many people think in terms of the "number" of "endpoints" (paths), and not the "number" of "operations" (paths * http methods).

  • Only the "file-per-path" option is semantically correct with the OpenAPI Specification 3.0.2. However, Redocly's openapi-cli will build valid bundles for any of the other options too.

Drawbacks

  • This may require multiple definitions per http method within a single file.
  • It requires settling on a path separator (that is allowed to be used in filenames) and sticking to that convention.