diff --git a/CHANGELOG.md b/CHANGELOG.md index fd4f082..6bdbd8b 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. +- 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 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 %} diff --git a/tests/res/example1-output-plain.md b/tests/res/example1-output-plain.md index 5abee8f..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 | | 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(email) + 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.