Why are names and descriptions discarded in Resources?

[DigTheDoug]

https://github.com/kminami/apib2swagger/blob/22678e5bcc5712d49135dee3cf5a24c429b3c6cb/index.js#L64C30-L64C30

In looking why our docs did not retain the categorization and description fields from the resources when converted from apib to open-api-3 I noticed in this comment above that the fields are specifically being discarded for resources. I couldn't find any history that listed a reason, but I'm curious why that is the case rather than include that info? Is it because the default swagger renderer doesn't display them in a great location, just putting them in the header?

I ask mostly because I feel in some cases the info is better to have than to totally leave out, even if it's not totally great looking, but also if using the Redoc renderer it displays much better and pretty close to some apib renderers.

As it currently displays discarding those fields:

With converted json keeping resource names and descriptions:

Redoc version with converted openapi json.

Sample apib data:

``` # Hello API Endpoints ## V1 Hello [/api/v1/hello/{?options}] Version 1 of the Hello API provides a number of helpful endpoints for testing and debugging. + Parameters + `options`: `displayText` (string, optional) - Some display text ### query param based methods [GET] + Response 200 (application/json) + Attributes (array[Metadata]) ## V2 Hello [/api/v2/hello/] Version 2 of the Hello API aims to provide a number of helpful endpoints for testing and debugging. ### Filtering, Ordering, & Pagination #### Filtering This API can filter returned metadata based on provided query parameters. The following fields can be used to filter results: - type - identifier - tag ```

[kminami]

It might be a behavior from OpenAPI 2.0 (a.k.a Swagger)'s restriction. OpenAPI 3 can keep that information as you said. I will improve this at next release of apib2swagger. Thank you!