From d1613f4d8f2c3978bd8f5f0279adc0ad591b0fda Mon Sep 17 00:00:00 2001 From: Roberto Prevato Date: Sun, 14 Apr 2024 08:52:28 +0200 Subject: [PATCH 1/5] Fix #39 --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index fd4f082..27ddf01 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Add OAS 3.1 support, cross-version warnings, and fix nullable spacing, by @dcode. - Fix MARKDOWN style table separators to use minimum 3 hyphens (issue #39), reported by @michael-nok. +- Add support for displaying descriptions of schema properties, requested by @Maia-Everett. ## [1.3.0] - 2025-11-19 From 17aecfd2e4d2c1d4064dda07783a85e3bb841f18 Mon Sep 17 00:00:00 2001 From: Roberto Prevato Date: Sun, 14 Apr 2024 08:58:22 +0200 Subject: [PATCH 2/5] Update example1-output-plain.md --- tests/res/example1-output-plain.md | 332 ++++++++++++++--------------- 1 file changed, 166 insertions(+), 166 deletions(-) diff --git a/tests/res/example1-output-plain.md b/tests/res/example1-output-plain.md index 5abee8f..0675a12 100644 --- a/tests/res/example1-output-plain.md +++ b/tests/res/example1-output-plain.md @@ -2953,328 +2953,328 @@ _Other possible types: text/json, text/plain_ ### Category -| Name | Type | -| --- | --- | -| creationTime | string(date-time) | -| description | string | null | -| eTag | string | -| id | string | null | -| name | string | -| releases | Array<[Release](#release)> | -| updateTime | string(date-time) | +| Name | Type | +| ------------ | -------------------------------- | +| creationTime | string(date-time) | +| description | string | null | +| eTag | string | +| id | string | null | +| name | string | +| releases | Array<[Release](#release)> | +| updateTime | string(date-time) | ### Country -| Name | Type | -| --- | --- | +| Name | Type | +| ----------- | ------------------ | | countryCode | string | null | -| id | string | null | -| name | string | +| id | string | null | +| name | string | ### CreateOrganizationsBoundInput -| Name | Type | -| --- | --- | +| Name | Type | +| ----- | -------------------------------------------------------------- | | items | Array<[OrganizationBoundInput](#organizationboundinput)> | ### CreateReleaseInput -| Name | Type | -| --- | --- | -| categoryId | string | -| countries | Array<string> | -| description | string | null | -| name | string | null | +| Name | Type | +| ----------- | ------------------- | +| categoryId | string | +| countries | Array<string> | +| description | string | null | +| name | string | null | ### CreateReleaseNodeInput -| Name | Type | -| --- | --- | -| fileId | string(uuid) | -| fileName | string | +| Name | Type | +| -------- | -------------- | +| fileId | string(uuid) | +| fileName | string | | fileSize | integer(int32) | -| fileType | string | +| fileType | string | ### CreateReleaseOutput -| Name | Type | -| --- | --- | -| id | string(uuid) | +| Name | Type | +| ---- | ------------ | +| id | string(uuid) | ### CurrentRelease -| Name | Type | -| --- | --- | -| categoryId | string | null | +| Name | Type | +| ----------- | ------------------ | +| categoryId | string | null | | countryCode | string | null | | countryName | string | null | -| publishTime | string(date-time) | -| releaseId | string(uuid) | +| publishTime | string(date-time) | +| releaseId | string(uuid) | | releaseName | string | null | ### DeleteReleaseNodeInput -| Name | Type | -| --- | --- | -| id | string(uuid) | +| Name | Type | +| ---- | ------------ | +| id | string(uuid) | ### FileDownloadStats -| Name | Type | -| --- | --- | +| Name | Type | +| --------------- | -------------- | | uniqueDownloads | integer(int32) | ### FileUrl -| Name | Type | -| --- | --- | -| url | string | null | +| Name | Type | +| ---- | ------------------ | +| url | string | null | ### GenericError -| Name | Type | -| --- | --- | -| code | integer(int32) | -| message | string | +| Name | Type | +| ------- | -------------- | +| code | integer(int32) | +| message | string | ### HealthCheck -| Name | Type | -| --- | --- | -| alive | boolean | +| Name | Type | +| ---------- | ------------------ | +| alive | boolean | | regionName | string | null | -| timestamp | string(date-time) | +| timestamp | string(date-time) | ### InitializeUploadInput -| Name | Type | -| --- | --- | -| fileName | string | null | -| fileSize | integer(int32) | -| fileType | string | null | -| releaseId | string(uuid) | +| Name | Type | +| --------- | ------------------ | +| fileName | string | null | +| fileSize | integer(int32) | +| fileType | string | null | +| releaseId | string(uuid) | ### InitializeUploadOutput -| Name | Type | -| --- | --- | -| baseURL | string | null | -| fileId | string | null | +| Name | Type | +| -------- | ------------------ | +| baseURL | string | null | +| fileId | string | null | | fileName | string | null | -| token | string | null | +| token | string | null | ### MetaData -| Name | Type | -| --- | --- | -| buildNumber | string | null | +| Name | Type | +| ------------ | ------------------ | +| buildNumber | string | null | | contactEmail | string | null | -| version | string | null | +| version | string | null | ### NodeInfo -| Name | Type | -| --- | --- | +| Name | Type | +| ------------ | ----------------- | | creationTime | string(date-time) | -| eTag | string | -| extension | string | -| icon | string | -| id | string(uuid) | -| name | string | -| size | integer(int32) | -| type | string | -| updateTime | string(date-time) | +| eTag | string | +| extension | string | +| icon | string | +| id | string(uuid) | +| name | string | +| size | integer(int32) | +| type | string | +| updateTime | string(date-time) | ### OrganizationBoundInput -| Name | Type | -| --- | --- | -| id | string(uuid) | +| Name | Type | +| ---- | ------------------ | +| id | string(uuid) | | name | string | null | ### ProfessionalContext -| Name | Type | -| --- | --- | +| Name | Type | +| ---------- | -------------------------------------------------------------- | | membership | Array<[ProfessionalMembership](#professionalmembership)> | -| signature | string | null | +| signature | string | null | ### ProfessionalMembership -| Name | Type | -| --- | --- | -| brandNames | Array<string> | -| categoryId | string | null | -| id | string(uuid) | -| marketCodes | Array<string> | -| organizationBrands | Array<string(uuid)> | -| organizationId | string(uuid) | +| Name | Type | +| ------------------- | ------------------------- | +| brandNames | Array<string> | +| categoryId | string | null | +| id | string(uuid) | +| marketCodes | Array<string> | +| organizationBrands | Array<string(uuid)> | +| organizationId | string(uuid) | | organizationMarkets | Array<string(uuid)> | -| organizationName | string | null | -| organizationNumber | string | null | -| role | string | null | -| scope | string | null | +| organizationName | string | null | +| organizationNumber | string | null | +| role | string | null | +| scope | string | null | ### PublishReleaseInput -| Name | Type | -| --- | --- | -| eTag | string | null | -| sendEmailNotifications | boolean | +| Name | Type | +| ---------------------- | ----------------- | +| eTag | string| null | +| sendEmailNotifications | boolean | ### Release -| Name | Type | -| --- | --- | -| category | [Category](#category) | -| categoryId | string | null | -| countries | Array<[ReleaseCountry](#releasecountry)> | -| creationTime | string(date-time) | -| description | string | null | -| draft | boolean | -| eTag | string | -| history | Array<[ReleaseHistory](#releasehistory)> | -| id | string(uuid) | -| name | string | -| nodes | Array<[ReleaseNode](#releasenode)> | -| organizations | Array<[ReleaseOrganization](#releaseorganization)> | -| requestedNotification | boolean | -| updateTime | string(date-time) | +| Name | Type | +| --------------------- | -------------------------------------------------------- | +| category | [Category](#category) | +| categoryId | string | null | +| countries | Array<[ReleaseCountry](#releasecountry)> | +| creationTime | string(date-time) | +| description | string | null | +| draft | boolean | +| eTag | string | +| history | Array<[ReleaseHistory](#releasehistory)> | +| id | string(uuid) | +| name | string | +| nodes | Array<[ReleaseNode](#releasenode)> | +| organizations | Array<[ReleaseOrganization](#releaseorganization)> | +| requestedNotification | boolean | +| updateTime | string(date-time) | ### ReleaseCountry -| Name | Type | -| --- | --- | -| country | [Country](#country) | -| countryId | string | null | -| release | [Release](#release) | -| releaseId | string(uuid) | +| Name | Type | +| --------- | ------------------- | +| country | [Country](#country) | +| countryId | string | null | +| release | [Release](#release) | +| releaseId | string(uuid) | ### ReleaseHistory -| Name | Type | -| --- | --- | -| data | string | null | -| description | string | -| id | string(uuid) | -| release | [Release](#release) | -| releaseId | string(uuid) | -| timeStamp | string(date-time) | -| user | string | +| Name | Type | +| ----------- | ------------------- | +| data | string | null | +| description | string | +| id | string(uuid) | +| release | [Release](#release) | +| releaseId | string(uuid) | +| timeStamp | string(date-time) | +| user | string | ### ReleaseNode -| Name | Type | -| --- | --- | -| id | string(uuid) | -| node | [NodeInfo](#nodeinfo) | -| nodeId | string(uuid) | -| release | [Release](#release) | -| releaseId | string(uuid) | +| Name | Type | +| --------- | --------------------- | +| id | string(uuid) | +| node | [NodeInfo](#nodeinfo) | +| nodeId | string(uuid) | +| release | [Release](#release) | +| releaseId | string(uuid) | ### ReleaseNodeDownload -| Name | Type | -| --- | --- | +| Name | Type | +| ----------------------------- | ------------------------ | | accessGrantedByOrganizationId | string(uuid) | null | -| id | string(uuid) | -| node | [NodeInfo](#nodeinfo) | -| nodeId | string(uuid) | -| release | [Release](#release) | -| releaseId | string(uuid) | -| timeStamp | string(date-time) | -| userEmail | string | -| userId | string | +| id | string(uuid) | +| node | [NodeInfo](#nodeinfo) | +| nodeId | string(uuid) | +| release | [Release](#release) | +| releaseId | string(uuid) | +| timeStamp | string(date-time) | +| userEmail | string | +| userId | string | ### ReleaseNodeDownloadPaginatedSet -| Name | Type | -| --- | --- | +| Name | Type | +| ----- | -------------------------------------------------------- | | items | Array<[ReleaseNodeDownload](#releasenodedownload)> | -| total | integer(int64) | +| total | integer(int64) | ### ReleaseOrganization -| Name | Type | -| --- | --- | -| displayName | string | null | -| organizationId | string(uuid) | -| release | [Release](#release) | -| releaseId | string(uuid) | +| Name | Type | +| -------------- | ------------------- | +| displayName | string | null | +| organizationId | string(uuid) | +| release | [Release](#release) | +| releaseId | string(uuid) | ### ReleasePaginatedSet -| Name | Type | -| --- | --- | +| Name | Type | +| ----- | -------------------------------- | | items | Array<[Release](#release)> | -| total | integer(int64) | +| total | integer(int64) | ### UpdateReleaseInput -| Name | Type | -| --- | --- | -| categoryId | string | -| countries | Array<string> | -| description | string | null | -| eTag | string | null | -| id | string(uuid) | -| name | string | null | +| Name | Type | +| ----------- | ------------------- | +| categoryId | string | +| countries | Array<string> | +| description | string | null | +| eTag | string | null | +| id | string(uuid) | +| name | string | null | @@ -3417,7 +3417,7 @@ This section describes common parameters that are reused across operations. ### PageNumber -| Name | In | Type | Default | Nullable | Description | +| Name | In | Type | Default | Nullable | Description | | ---- | --- | ---- | ------- | -------- | ----------- | From 23d2037554059b974aa520cb268fc29ca9ec2321 Mon Sep 17 00:00:00 2001 From: Roberto Prevato Date: Sun, 14 Apr 2024 10:40:54 +0200 Subject: [PATCH 3/5] Fix #45 --- openapidocs/mk/v3/views_markdown/partial/type.html | 6 +++--- openapidocs/mk/v3/views_mkdocs/partial/type.html | 2 ++ 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/openapidocs/mk/v3/views_markdown/partial/type.html b/openapidocs/mk/v3/views_markdown/partial/type.html index 108c719..f71aaf3 100644 --- a/openapidocs/mk/v3/views_markdown/partial/type.html +++ b/openapidocs/mk/v3/views_markdown/partial/type.html @@ -1,10 +1,10 @@ {% if get_primary_type(definition.type) == "object" %} {%- with props = handler.get_properties(definition) -%} {% if props %} -| {{texts.name}} | {{texts.type}} | -| --- | --- | +| {{texts.name}} | {{texts.type}} | {{texts.description}} | +| --- | --- | --- | {%- for name, schema in props %} -| {{name}} | {% include "partial/schema-repr.html" %} | +| {{name}} | {% include "partial/schema-repr.html" %} | {{schema.description}} | {%- endfor -%} {%- endif %} {%- endwith -%} diff --git a/openapidocs/mk/v3/views_mkdocs/partial/type.html b/openapidocs/mk/v3/views_mkdocs/partial/type.html index 3de5d60..42e4968 100644 --- a/openapidocs/mk/v3/views_mkdocs/partial/type.html +++ b/openapidocs/mk/v3/views_mkdocs/partial/type.html @@ -6,6 +6,7 @@ {{texts.name}} {{texts.type}} + {{texts.description}} @@ -13,6 +14,7 @@ {{name}} {% include "partial/schema-repr.html" %} + {{schema.description}} {%- endfor %} From 9563c8b6703ba6c8472b67f47455d227586bc5ff Mon Sep 17 00:00:00 2001 From: Roberto Prevato Date: Fri, 6 Mar 2026 19:32:42 +0100 Subject: [PATCH 4/5] Update snapshots for description column added in Fix #45 The type templates were updated to include a Description column but the snapshot files used by tests were not regenerated. Regenerate them to match the new template output. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- tests/res/example1-output-plain.md | 366 ++++++++++++++--------------- tests/res/example1-output.md | 177 ++++++++++++++ tests/res/example2-output.md | 18 ++ tests/res/example3-output.md | 18 ++ tests/res/example4-split-output.md | 26 ++ 5 files changed, 422 insertions(+), 183 deletions(-) diff --git a/tests/res/example1-output-plain.md b/tests/res/example1-output-plain.md index 0675a12..c53e97f 100644 --- a/tests/res/example1-output-plain.md +++ b/tests/res/example1-output-plain.md @@ -2953,328 +2953,328 @@ _Other possible types: text/json, text/plain_ ### Category -| Name | Type | -| ------------ | -------------------------------- | -| creationTime | string(date-time) | -| description | string | null | -| eTag | string | -| id | string | null | -| name | string | -| releases | Array<[Release](#release)> | -| updateTime | string(date-time) | +| Name | Type | Description | +| --- | --- | --- | +| creationTime | string(date-time) | | +| description | string | null | | +| eTag | string | | +| id | string | null | | +| name | string | | +| releases | Array<[Release](#release)> | | +| updateTime | string(date-time) | | ### Country -| Name | Type | -| ----------- | ------------------ | -| countryCode | string | null | -| id | string | null | -| name | string | +| Name | Type | Description | +| --- | --- | --- | +| countryCode | string | null | | +| id | string | null | | +| name | string | | ### CreateOrganizationsBoundInput -| Name | Type | -| ----- | -------------------------------------------------------------- | -| items | Array<[OrganizationBoundInput](#organizationboundinput)> | +| Name | Type | Description | +| --- | --- | --- | +| items | Array<[OrganizationBoundInput](#organizationboundinput)> | | ### CreateReleaseInput -| Name | Type | -| ----------- | ------------------- | -| categoryId | string | -| countries | Array<string> | -| description | string | null | -| name | string | null | +| Name | Type | Description | +| --- | --- | --- | +| categoryId | string | | +| countries | Array<string> | | +| description | string | null | | +| name | string | null | | ### CreateReleaseNodeInput -| Name | Type | -| -------- | -------------- | -| fileId | string(uuid) | -| fileName | string | -| fileSize | integer(int32) | -| fileType | string | +| Name | Type | Description | +| --- | --- | --- | +| fileId | string(uuid) | | +| fileName | string | | +| fileSize | integer(int32) | | +| fileType | string | | ### CreateReleaseOutput -| Name | Type | -| ---- | ------------ | -| id | string(uuid) | +| Name | Type | Description | +| --- | --- | --- | +| id | string(uuid) | | ### CurrentRelease -| Name | Type | -| ----------- | ------------------ | -| categoryId | string | null | -| countryCode | string | null | -| countryName | string | null | -| publishTime | string(date-time) | -| releaseId | string(uuid) | -| releaseName | string | null | +| Name | Type | Description | +| --- | --- | --- | +| categoryId | string | null | | +| countryCode | string | null | | +| countryName | string | null | | +| publishTime | string(date-time) | | +| releaseId | string(uuid) | | +| releaseName | string | null | | ### DeleteReleaseNodeInput -| Name | Type | -| ---- | ------------ | -| id | string(uuid) | +| Name | Type | Description | +| --- | --- | --- | +| id | string(uuid) | | ### FileDownloadStats -| Name | Type | -| --------------- | -------------- | -| uniqueDownloads | integer(int32) | +| Name | Type | Description | +| --- | --- | --- | +| uniqueDownloads | integer(int32) | | ### FileUrl -| Name | Type | -| ---- | ------------------ | -| url | string | null | +| Name | Type | Description | +| --- | --- | --- | +| url | string | null | | ### GenericError -| Name | Type | -| ------- | -------------- | -| code | integer(int32) | -| message | string | +| Name | Type | Description | +| --- | --- | --- | +| code | integer(int32) | | +| message | string | | ### HealthCheck -| Name | Type | -| ---------- | ------------------ | -| alive | boolean | -| regionName | string | null | -| timestamp | string(date-time) | +| Name | Type | Description | +| --- | --- | --- | +| alive | boolean | | +| regionName | string | null | | +| timestamp | string(date-time) | | ### InitializeUploadInput -| Name | Type | -| --------- | ------------------ | -| fileName | string | null | -| fileSize | integer(int32) | -| fileType | string | null | -| releaseId | string(uuid) | +| Name | Type | Description | +| --- | --- | --- | +| fileName | string | null | | +| fileSize | integer(int32) | | +| fileType | string | null | | +| releaseId | string(uuid) | | ### InitializeUploadOutput -| Name | Type | -| -------- | ------------------ | -| baseURL | string | null | -| fileId | string | null | -| fileName | string | null | -| token | string | null | +| Name | Type | Description | +| --- | --- | --- | +| baseURL | string | null | | +| fileId | string | null | | +| fileName | string | null | | +| token | string | null | | ### MetaData -| Name | Type | -| ------------ | ------------------ | -| buildNumber | string | null | -| contactEmail | string | null | -| version | string | null | +| Name | Type | Description | +| --- | --- | --- | +| buildNumber | string | null | | +| contactEmail | string | null | | +| version | string | null | | ### NodeInfo -| Name | Type | -| ------------ | ----------------- | -| creationTime | string(date-time) | -| eTag | string | -| extension | string | -| icon | string | -| id | string(uuid) | -| name | string | -| size | integer(int32) | -| type | string | -| updateTime | string(date-time) | +| Name | Type | Description | +| --- | --- | --- | +| creationTime | string(date-time) | | +| eTag | string | | +| extension | string | | +| icon | string | | +| id | string(uuid) | | +| name | string | | +| size | integer(int32) | | +| type | string | | +| updateTime | string(date-time) | | ### OrganizationBoundInput -| Name | Type | -| ---- | ------------------ | -| id | string(uuid) | -| name | string | null | +| Name | Type | Description | +| --- | --- | --- | +| id | string(uuid) | | +| name | string | null | | ### ProfessionalContext -| Name | Type | -| ---------- | -------------------------------------------------------------- | -| membership | Array<[ProfessionalMembership](#professionalmembership)> | -| signature | string | null | +| Name | Type | Description | +| --- | --- | --- | +| membership | Array<[ProfessionalMembership](#professionalmembership)> | | +| signature | string | null | | ### ProfessionalMembership -| Name | Type | -| ------------------- | ------------------------- | -| brandNames | Array<string> | -| categoryId | string | null | -| id | string(uuid) | -| marketCodes | Array<string> | -| organizationBrands | Array<string(uuid)> | -| organizationId | string(uuid) | -| organizationMarkets | Array<string(uuid)> | -| organizationName | string | null | -| organizationNumber | string | null | -| role | string | null | -| scope | string | null | +| Name | Type | Description | +| --- | --- | --- | +| brandNames | Array<string> | | +| categoryId | string | null | | +| id | string(uuid) | | +| marketCodes | Array<string> | | +| organizationBrands | Array<string(uuid)> | | +| organizationId | string(uuid) | | +| organizationMarkets | Array<string(uuid)> | | +| organizationName | string | null | | +| organizationNumber | string | null | | +| role | string | null | | +| scope | string | null | | ### PublishReleaseInput -| Name | Type | -| ---------------------- | ----------------- | -| eTag | string| null | -| sendEmailNotifications | boolean | +| Name | Type | Description | +| --- | --- | --- | +| eTag | string | null | | +| sendEmailNotifications | boolean | | ### Release -| Name | Type | -| --------------------- | -------------------------------------------------------- | -| category | [Category](#category) | -| categoryId | string | null | -| countries | Array<[ReleaseCountry](#releasecountry)> | -| creationTime | string(date-time) | -| description | string | null | -| draft | boolean | -| eTag | string | -| history | Array<[ReleaseHistory](#releasehistory)> | -| id | string(uuid) | -| name | string | -| nodes | Array<[ReleaseNode](#releasenode)> | -| organizations | Array<[ReleaseOrganization](#releaseorganization)> | -| requestedNotification | boolean | -| updateTime | string(date-time) | +| Name | Type | Description | +| --- | --- | --- | +| category | [Category](#category) | | +| categoryId | string | null | | +| countries | Array<[ReleaseCountry](#releasecountry)> | | +| creationTime | string(date-time) | | +| description | string | null | | +| draft | boolean | | +| eTag | string | | +| history | Array<[ReleaseHistory](#releasehistory)> | | +| id | string(uuid) | | +| name | string | | +| nodes | Array<[ReleaseNode](#releasenode)> | | +| organizations | Array<[ReleaseOrganization](#releaseorganization)> | | +| requestedNotification | boolean | | +| updateTime | string(date-time) | | ### ReleaseCountry -| Name | Type | -| --------- | ------------------- | -| country | [Country](#country) | -| countryId | string | null | -| release | [Release](#release) | -| releaseId | string(uuid) | +| Name | Type | Description | +| --- | --- | --- | +| country | [Country](#country) | | +| countryId | string | null | | +| release | [Release](#release) | | +| releaseId | string(uuid) | | ### ReleaseHistory -| Name | Type | -| ----------- | ------------------- | -| data | string | null | -| description | string | -| id | string(uuid) | -| release | [Release](#release) | -| releaseId | string(uuid) | -| timeStamp | string(date-time) | -| user | string | +| Name | Type | Description | +| --- | --- | --- | +| data | string | null | | +| description | string | | +| id | string(uuid) | | +| release | [Release](#release) | | +| releaseId | string(uuid) | | +| timeStamp | string(date-time) | | +| user | string | | ### ReleaseNode -| Name | Type | -| --------- | --------------------- | -| id | string(uuid) | -| node | [NodeInfo](#nodeinfo) | -| nodeId | string(uuid) | -| release | [Release](#release) | -| releaseId | string(uuid) | +| Name | Type | Description | +| --- | --- | --- | +| id | string(uuid) | | +| node | [NodeInfo](#nodeinfo) | | +| nodeId | string(uuid) | | +| release | [Release](#release) | | +| releaseId | string(uuid) | | ### ReleaseNodeDownload -| Name | Type | -| ----------------------------- | ------------------------ | -| accessGrantedByOrganizationId | string(uuid) | null | -| id | string(uuid) | -| node | [NodeInfo](#nodeinfo) | -| nodeId | string(uuid) | -| release | [Release](#release) | -| releaseId | string(uuid) | -| timeStamp | string(date-time) | -| userEmail | string | -| userId | string | +| Name | Type | Description | +| --- | --- | --- | +| accessGrantedByOrganizationId | string(uuid) | null | | +| id | string(uuid) | | +| node | [NodeInfo](#nodeinfo) | | +| nodeId | string(uuid) | | +| release | [Release](#release) | | +| releaseId | string(uuid) | | +| timeStamp | string(date-time) | | +| userEmail | string | | +| userId | string | | ### ReleaseNodeDownloadPaginatedSet -| Name | Type | -| ----- | -------------------------------------------------------- | -| items | Array<[ReleaseNodeDownload](#releasenodedownload)> | -| total | integer(int64) | +| Name | Type | Description | +| --- | --- | --- | +| items | Array<[ReleaseNodeDownload](#releasenodedownload)> | | +| total | integer(int64) | | ### ReleaseOrganization -| Name | Type | -| -------------- | ------------------- | -| displayName | string | null | -| organizationId | string(uuid) | -| release | [Release](#release) | -| releaseId | string(uuid) | +| Name | Type | Description | +| --- | --- | --- | +| displayName | string | null | | +| organizationId | string(uuid) | | +| release | [Release](#release) | | +| releaseId | string(uuid) | | ### ReleasePaginatedSet -| Name | Type | -| ----- | -------------------------------- | -| items | Array<[Release](#release)> | -| total | integer(int64) | +| Name | Type | Description | +| --- | --- | --- | +| items | Array<[Release](#release)> | | +| total | integer(int64) | | ### UpdateReleaseInput -| Name | Type | -| ----------- | ------------------- | -| categoryId | string | -| countries | Array<string> | -| description | string | null | -| eTag | string | null | -| id | string(uuid) | -| name | string | null | +| Name | Type | Description | +| --- | --- | --- | +| categoryId | string | | +| countries | Array<string> | | +| description | string | null | | +| eTag | string | null | | +| id | string(uuid) | | +| name | string | null | | @@ -3417,7 +3417,7 @@ This section describes common parameters that are reused across operations. ### PageNumber -| Name | In | Type | Default | Nullable | Description | +| Name | In | Type | Default | Nullable | Description | | ---- | --- | ---- | ------- | -------- | ----------- | diff --git a/tests/res/example1-output.md b/tests/res/example1-output.md index e207e9b..1f56d5c 100644 --- a/tests/res/example1-output.md +++ b/tests/res/example1-output.md @@ -43,6 +43,7 @@ Optional multiline or single-line description in ## Blobs +
### POST /api/blobs/initialize-upload @@ -216,6 +217,7 @@ Initializes a file upload operation. ## Categories +
### GET /api/categories @@ -349,6 +351,7 @@ Gets the list of categories supported by the system. ## Countries +
### GET /api/countries @@ -412,6 +415,7 @@ codes. +
### GET /api/system-countries @@ -479,6 +483,7 @@ ISO country codes. ## Downloads +
### GET /api/downloads @@ -690,6 +695,7 @@ Gets a paginated set of downloads records. ## Health +
### GET /api/health @@ -765,6 +771,7 @@ API health check ## Professionals +
### GET /api/pro/own-context @@ -861,6 +868,7 @@ API health check ## Info +
### GET /api/info @@ -937,6 +945,7 @@ Returns information about the API itself. ## Releases +
### GET /api/releases/{releaseId} @@ -1159,6 +1168,7 @@ Returns details about a release by id. ``` +
### DELETE /api/releases/{releaseId} @@ -1200,6 +1210,7 @@ Deletes a release by id.

Response 200 OK

+
### PATCH /api/releases/{releaseId} @@ -1487,6 +1498,7 @@ Deletes a release by id. +
### GET /api/releases @@ -1683,6 +1695,7 @@ Deletes a release by id. ``` +
### POST /api/releases @@ -1799,6 +1812,7 @@ Deletes a release by id. +
### GET /api/current-releases @@ -1864,6 +1878,7 @@ Deletes a release by id. +
### GET /api/orgs/current-releases @@ -1929,6 +1944,7 @@ Deletes a release by id. +
### GET /api/releases/{releaseId}/history @@ -2062,6 +2078,7 @@ Deletes a release by id. +
### GET /api/releases/{releaseId}/file/{nodeId} @@ -2140,6 +2157,7 @@ Deletes a release by id. +
### GET /api/releases/{releaseId}/file/{nodeId}/downloads @@ -2218,6 +2236,7 @@ Deletes a release by id. +
### PUT /api/releases/{releaseId}/files @@ -2473,6 +2492,7 @@ Deletes a release by id. ``` +
### DELETE /api/releases/{releaseId}/files @@ -2726,6 +2746,7 @@ Deletes a release by id. +
### PUT /api/releases/{releaseId}/orgs @@ -2987,6 +3008,7 @@ Deletes a release by id. ``` +
### DELETE /api/releases/{releaseId}/orgs @@ -3239,6 +3261,7 @@ Deletes a release by id. +
### POST /api/releases/{releaseId}/clone @@ -3462,6 +3485,7 @@ Deletes a release by id. +
### POST /api/releases/{releaseId}/publish @@ -3734,36 +3758,44 @@ Deletes a release by id. Name Type + Description creationTime string(date-time) + description string | null + eTag string + id string | null + name string + releases Array<Release> + updateTime string(date-time) + @@ -3777,20 +3809,24 @@ Deletes a release by id. Name Type + Description countryCode string | null + id string | null + name string + @@ -3804,12 +3840,14 @@ Deletes a release by id. Name Type + Description items Array<OrganizationBoundInput> + @@ -3823,24 +3861,29 @@ Deletes a release by id. Name Type + Description categoryId string + countries Array<string> + description string | null + name string | null + @@ -3854,24 +3897,29 @@ Deletes a release by id. Name Type + Description fileId string(uuid) + fileName string + fileSize integer(int32) + fileType string + @@ -3885,12 +3933,14 @@ Deletes a release by id. Name Type + Description id string(uuid) + @@ -3904,32 +3954,39 @@ Deletes a release by id. Name Type + Description categoryId string | null + countryCode string | null + countryName string | null + publishTime string(date-time) + releaseId string(uuid) + releaseName string | null + @@ -3943,12 +4000,14 @@ Deletes a release by id. Name Type + Description id string(uuid) + @@ -3962,12 +4021,14 @@ Deletes a release by id. Name Type + Description uniqueDownloads integer(int32) + @@ -3981,12 +4042,14 @@ Deletes a release by id. Name Type + Description url string | null + @@ -4000,16 +4063,19 @@ Deletes a release by id. Name Type + Description code integer(int32) + message string + @@ -4023,20 +4089,24 @@ Deletes a release by id. Name Type + Description alive boolean + regionName string | null + timestamp string(date-time) + @@ -4050,24 +4120,29 @@ Deletes a release by id. Name Type + Description fileName string | null + fileSize integer(int32) + fileType string | null + releaseId string(uuid) + @@ -4081,24 +4156,29 @@ Deletes a release by id. Name Type + Description baseURL string | null + fileId string | null + fileName string | null + token string | null + @@ -4112,20 +4192,24 @@ Deletes a release by id. Name Type + Description buildNumber string | null + contactEmail string | null + version string | null + @@ -4139,44 +4223,54 @@ Deletes a release by id. Name Type + Description creationTime string(date-time) + eTag string + extension string + icon string + id string(uuid) + name string + size integer(int32) + type string + updateTime string(date-time) + @@ -4190,16 +4284,19 @@ Deletes a release by id. Name Type + Description id string(uuid) + name string | null + @@ -4213,16 +4310,19 @@ Deletes a release by id. Name Type + Description membership Array<ProfessionalMembership> + signature string | null + @@ -4236,52 +4336,64 @@ Deletes a release by id. Name Type + Description brandNames Array<string> + categoryId string | null + id string(uuid) + marketCodes Array<string> + organizationBrands Array<string(uuid)> + organizationId string(uuid) + organizationMarkets Array<string(uuid)> + organizationName string | null + organizationNumber string | null + role string | null + scope string | null + @@ -4295,16 +4407,19 @@ Deletes a release by id. Name Type + Description eTag string | null + sendEmailNotifications boolean + @@ -4318,64 +4433,79 @@ Deletes a release by id. Name Type + Description category Category + categoryId string | null + countries Array<ReleaseCountry> + creationTime string(date-time) + description string | null + draft boolean + eTag string + history Array<ReleaseHistory> + id string(uuid) + name string + nodes Array<ReleaseNode> + organizations Array<ReleaseOrganization> + requestedNotification boolean + updateTime string(date-time) + @@ -4389,24 +4519,29 @@ Deletes a release by id. Name Type + Description country Country + countryId string | null + release Release + releaseId string(uuid) + @@ -4420,36 +4555,44 @@ Deletes a release by id. Name Type + Description data string | null + description string + id string(uuid) + release Release + releaseId string(uuid) + timeStamp string(date-time) + user string + @@ -4463,28 +4606,34 @@ Deletes a release by id. Name Type + Description id string(uuid) + node NodeInfo + nodeId string(uuid) + release Release + releaseId string(uuid) + @@ -4498,44 +4647,54 @@ Deletes a release by id. Name Type + Description accessGrantedByOrganizationId string(uuid) | null + id string(uuid) + node NodeInfo + nodeId string(uuid) + release Release + releaseId string(uuid) + timeStamp string(date-time) + userEmail string + userId string + @@ -4549,16 +4708,19 @@ Deletes a release by id. Name Type + Description items Array<ReleaseNodeDownload> + total integer(int64) + @@ -4572,24 +4734,29 @@ Deletes a release by id. Name Type + Description displayName string | null + organizationId string(uuid) + release Release + releaseId string(uuid) + @@ -4603,16 +4770,19 @@ Deletes a release by id. Name Type + Description items Array<Release> + total integer(int64) + @@ -4626,32 +4796,39 @@ Deletes a release by id. Name Type + Description categoryId string + countries Array<string> + description string | null + eTag string | null + id string(uuid) + name string | null + diff --git a/tests/res/example2-output.md b/tests/res/example2-output.md index f15167a..5bb5c0b 100644 --- a/tests/res/example2-output.md +++ b/tests/res/example2-output.md @@ -33,6 +33,7 @@ Most likely, it is not desirable to edit this file by hand! ## pets +
### GET /pets @@ -171,6 +172,7 @@ List all pets ``` +
### POST /pets @@ -252,6 +254,7 @@ Create a pet +
### GET /pets/{petId} @@ -388,6 +391,7 @@ Info for a specific pet ``` +
### PATCH /pets/{petId} @@ -467,16 +471,19 @@ Info for a specific pet Name Type + Description age integer + hunts boolean + @@ -490,16 +497,19 @@ Info for a specific pet Name Type + Description bark boolean + breed string + @@ -513,16 +523,19 @@ Info for a specific pet Name Type + Description code integer(int32) + message string + @@ -536,24 +549,29 @@ Info for a specific pet Name Type + Description category string + id integer(int64) + name string + tag string + diff --git a/tests/res/example3-output.md b/tests/res/example3-output.md index e86c596..7c32185 100644 --- a/tests/res/example3-output.md +++ b/tests/res/example3-output.md @@ -33,6 +33,7 @@ Most likely, it is not desirable to edit this file by hand! ## pets +
### GET /pets @@ -155,6 +156,7 @@ List all pets ``` +
### POST /pets @@ -203,6 +205,7 @@ Create a pet +
### GET /pets/{petId} @@ -323,6 +326,7 @@ Info for a specific pet ``` +
### PATCH /pets/{petId} @@ -369,16 +373,19 @@ Info for a specific pet Name Type + Description age integer + hunts boolean + @@ -392,16 +399,19 @@ Info for a specific pet Name Type + Description bark boolean + breed string + @@ -415,16 +425,19 @@ Info for a specific pet Name Type + Description code integer(int32) + message string + @@ -438,24 +451,29 @@ Info for a specific pet Name Type + Description category string + id integer(int64) + name string + tag string + diff --git a/tests/res/example4-split-output.md b/tests/res/example4-split-output.md index 5ac657e..77c4e22 100644 --- a/tests/res/example4-split-output.md +++ b/tests/res/example4-split-output.md @@ -34,6 +34,7 @@ split Public API ## User +
### POST /users @@ -157,6 +158,7 @@ Invite a user Response 401 Unauthorized

Refer to the common response description: Unauthorized.

+
### GET /users @@ -270,6 +272,7 @@ Retrieve all users

Refer to the common response description: Unauthorized.

+
### GET /users/{identifier} @@ -321,6 +324,7 @@ Get user by ID/Email Response 401 Unauthorized

Refer to the common response description: Unauthorized.

+
### DELETE /users/{identifier} @@ -395,20 +399,24 @@ Delete user by ID/Email Name Type + Description code string + description string + message string + @@ -422,28 +430,34 @@ Delete user by ID/Email Name Type + Description createdAt string(date-time) + Time the role was created. id number + name string + scope string + updatedAt string(date-time) + Last time the role was updaded. @@ -457,16 +471,19 @@ Delete user by ID/Email Name Type + Description data Array<UserInformation> + nextCursor string | null + Paginate through users by setting the cursor parameter to a nextCursor attribute returned by a previous request. Default value fetches the first "page" of the collection. @@ -480,40 +497,49 @@ Delete user by ID/Email Name Type + Description createdAt string(date-time) + Time the user was created. email string() + firstName string + User's first name globalRole RoleInformation + id string + isPending boolean + Whether the user finished setting up their account in response to the invitation (true) or not (false). lastName string + User's last name updatedAt string(date-time) + Last time the user was updated. From 467929d9103eb2580aebc1b9ecf4d15088749f5e Mon Sep 17 00:00:00 2001 From: Roberto Prevato Date: Fri, 6 Mar 2026 19:53:59 +0100 Subject: [PATCH 5/5] Update CHANGELOG.md --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 27ddf01..6bdbd8b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Add OAS 3.1 support, cross-version warnings, and fix nullable spacing, by @dcode. - Fix MARKDOWN style table separators to use minimum 3 hyphens (issue #39), reported by @michael-nok. -- Add support for displaying descriptions of schema properties, requested by @Maia-Everett. +- Fix [#45](https://github.com/Neoteroi/essentials-openapi/issues/45): add support for displaying descriptions of schema properties, reported by @Maia-Everett. ## [1.3.0] - 2025-11-19