Link to schema from description etc
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 25.9k
- Forks
- 2.4k
- Avg merge
- 13h 10m
- Merged PRs (30d)
- 4
Description
Is it possible to create links and/or embed other schemas in the description of a property?
I saw that in #681, support for <SchemaDefinition> tags was added, but apparently only to tag descriptions?
My use case is this: The API has multiple instances of encrypted data containers. In encrypted form, the data always has the same structure (containing a public key fingerprint, an ephemeral key encrypted with said public key, etc - standard hybrid encryption), so this is defined in a re-used schema obviously. But it's also useful to describe the schema for the raw/source JSON data once the encrypted data container is decrypted, so API consumers know how to parse the decrypted data.
Example:
EncryptedData:
description: Generic encrypted representation of arbitrary data
type: object
properties:
data:
type: string
format: byte
description: The data encrypted with the ephemeral key
encryptedKey:
type: string
description: The ephemeral AES key, encrypted with the public RSA key
publicKeyFingerprint:
type: string
description: The fingerprint of the public RSA key
Some.SourceData:
type: object
description: Some data we want to encrypt
properties:
foo: {type: string}
bar: {type: integer}
Some.Request:
type: object
properties:
encryptedData:
allOf:
- description: Encrypted data container containing the encrypted representation of a `Some.SourceData` object
- $ref: '#/EncryptedData'
In this case, Some.Request contains an encrypted container of a Some.SourceData object (so you'd get the raw object from something like JSON.parse(decrypt(req.body.encryptedData))).
In my spec, I've included the schemas for the decrypted raw representation as well, but it will be an orphaned object without any references to it, since it's not actually part of any other schema or API, it's only there to describe the schema of another object after it's been decrypted (or before it's been encrypted).
To at least include it in my documentation, it would be nice if I could link to it so that when viewing the Some.Request operation, I can expand it and find that encryptedData is of type EncryptedData but in decrypted form it'll be a Some.SourceData.
I think that this would be possible if <SchemaDefinition> were supported on any description element, but maybe that makes the layout too complex? Is there any other way to link one schema description to another, or in any other way achieve what I'm after?
Or should I consider the schema of decoded/decrypted objects separate entities and leave them out of my API altogether? It seems reasonablethat a server implementing this API would get a Some.Request request, validate that the body matches the schema, i.e., that encryptedData is valid, then decrypt encryptedData, parse it into a object, and then validate it using the schema of the raw data.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the existing support referenced in #681 and how property descriptions are rendered. Define whether links or embedded schema references should work in arbitrary descriptions, then verify that the encryptedData example makes Some.SourceData discoverable from the operation documentation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100