Open razor-x opened 1 week ago
How about something like this?
# `acs_system`
Represents an [access control system](https://docs.seam.co/latest/capability-guides/access-systems).
## Properties
### `acs_system_id`
Format: `ID`
ID of the `acs_system`.
---
# Endpoints
## [`/acs/systems/get`](./get.md)
Returns a specified [access control system](https://docs.seam.co/latest/capability-guides/access-systems).
---
# Events
## `Event 1`
Event 1 description.
<details>
<summary>Event 1 Properties</summary>
### `event1prop1`
Format: `format`
Event 1 prop 1 description.
</details>
---
# Errors
## `Error 1`
Error 1 description.
---
# Warnings
## `Warning 1`
Warning 1 description.
---
Question 1: How do we show the format of the errors and warnings? I'm assuming that they're all based on the same error and warning objects, so all errors should have the same set of props, and all warnings should have the same set of props. Is that correct? Is there a way in which we could link to a definition of the error object and the warning object instead of repeating the same prop descriptions over and over again?
Question 2: Right now, Events is an H1, at the same level as the resource. If events, errors, and warnings are specifically linked to the resource (not the route), should we shift all the heading levels down one for events, errors, and warnings?
# `acs_system`
Represents an [access control system](https://docs.seam.co/latest/capability-guides/access-systems).
## Properties
### `acs_system_id`
Format: `ID`
ID of the `acs_system`.
---
## Events
### `Event 1`
Event 1 description.
<details>
<summary>Event 1 Properties</summary>
#### `event1prop1`
Format: `format`
Event 1 prop 1 description.
</details>
---
## Errors
### `Error 1`
Error 1 description.
---
## Warnings
### `Warning 1`
Warning 1 description.
---
# Endpoints
## [`/acs/systems/get`](./get.md)
Returns a specified [access control system](https://docs.seam.co/latest/capability-guides/access-systems).
---
all errors should have the same set of props, and all warnings should have the same set of props. Is that correct?
Mostly, however now that we can document and type these, I'd like errors and warnings to have more helpful props. Some already do, e.g., we have devices_connected_to_other_account
with a device_ids
prop.
I'd say Events are linked to the route, since we have lock.unlocked
for example. We could document lock.unlocked
under /devices
device resource, but it would make more send to consider that event under /locks
.
@razor-x, am I correct in understanding that rendering errors/warnings currently cannot be supported since they are not properly documented on seam-connect? Most error/warning schemas are defined something like this:
z.array(
z.object({
error_code: z.string(),
message: z.string(),
})
)
We will have separate errors and warnings sections that are children of the resource and look similar to the props section.