You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
OpenAPI doc leaves out read-only fields and types some strings as object #470
OPENAPI_DOC.yml leaves out the read-only fields that the API sends, and it gives some string fields the type object. A client generated from the document drops the missing fields and cannot type the strings. I compared the replies of 123 GET endpoints on a local stack with the document at f30710c, then checked each field in the source.
Read-only fields are missing
JSON::Schema#json_schema skips each instance variable with ignore or ignore_deserialize (json-schema json-schema.cr#L15). A request body must not have these fields. The document uses the same schema for the response, though, and the API sends them.
OpenAPI 3.1 has readOnly: true for this case. If json-schema keeps these fields with readOnly, the document can describe both directions with one schema.
User.AdminMetadataResponse and User.PublicMetadataResponse do not have associated_metadata either. define_to_json adds it with methods: (user.cr#L308-L317). subsystem_access comes from the same methods: list and is in the document. The difference may be that associated_metadata has no return type.
String fields have the type object
introspect gives { type: "object" } for a type it does not know (json-schema.cr#L189-L196). The API sends these fields as strings:
After #469 the field hints reach the schema, so type: "string" on each of these fields may be enough.
The JSON::Any fields also get object, but they can hold any JSON value. Metadata::Interface.details holds arrays in the seed data, for example. An empty schema ({}) means any value.
Other differences
The API sends the number of an enum that has Enum::ValueConverter, but the document lists the names: Broker.auth_type (2), Driver.role and Module.role (99), Settings.encryption_level (0).
The {id} path parameter of /api/engine/v2/oauth_apps/{id} is a string, but DoorkeeperApplication.id is an integer.
PlaceOS/ts-client#36 gets generator patches for these fields. Each patch stops the generator when the document changes the field, so a fix here shows there.
Activity
fix: patch string fields and missing read-only fields in the documents