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

Add path metadata #329

Merged
merged 1 commit into from
Oct 10, 2024
Merged

Add path metadata #329

merged 1 commit into from
Oct 10, 2024

Conversation

razor-x
Copy link
Contributor

@razor-x razor-x commented Sep 6, 2024

This adds a new file src/data/paths.yaml for injecting content or information that is not supported by blueprint. Ideally, we do not need this file, however adding some features to blueprint may be more complicated, or out of scope beyond the docs. We can use this file to move faster to meet documentation requirements in those cases.

If we decide some content will never move upstream, we can move it out of src/data/paths.yaml into something more specific to the docs, similar to how code-samples work.

This PR introduces three new properties:

  1. description for routes (and eventually namespaces).
  2. events (unused but needed soon)
  3. resources to add additional resources that should be documented under a route but may not be returned by an endpoint under that route. I'm not sure if we need this one yet, but this is really a starting point to experiment with how to document relevant properties and resources in other contexts, e.g., should EVERY device property be documented under /devices AND /thermostats? Or should some properties by included / excluded on those routes.

@razor-x razor-x marked this pull request as ready for review September 6, 2024 23:46
@razor-x razor-x requested a review from a team as a code owner September 6, 2024 23:46
---
/acs/systems:
description: null
events: []
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe this should support wildcards, e.g., events: [ 'lock.*' ]

@razor-x
Copy link
Contributor Author

razor-x commented Oct 10, 2024

I am only adding description in the PR. We will use this as an extension point later as needed.

@razor-x razor-x merged commit 38b76a8 into main Oct 10, 2024
12 checks passed
@razor-x razor-x deleted the path-meta branch October 10, 2024 23:33
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

Successfully merging this pull request may close these issues.

Support description for routes and namespaces
2 participants