Field value limited at 1024 for top-level description.

[upvest-juha]

Upload of an OpenAPI spec v 3.0.3 fails when it has a long documentation bit inside top-level description-field in the beginning because you have a limit of varchar 1024 in there somewhere.

io.apicurio.registry.storage.RegistryStorageException: org.jdbi.v3.core.statement.UnableToExecuteStatementException: org.postgresql.util.PSQLException: ERROR: value too long for type character varying(1024) [statement:"INSERT INTO versions (globalId, tenantId, groupId, artifactId, version, versionId, state, name, description, createdBy, createdOn, labels, properties, contentId) VALUES (?, ?, ?, ?, ?, 1, ?, ?, ?, ?, ?, ?, ?, ?)", arguments:{positional:{0:8,1:_,2:public,3:investment-api-public-draft-01,4:1,5:ENABLED,6:Upvest Investment API,7:Upvest Retail Investment API for Securities and Cryptocurrencies.
...
...

It is common to have generic documentation inside the field and this should really allow any length field. This is what it looks like in Swagger UI.

[EricWittmann]

This bug has been fixed by this commit: ad6ad31

It will be fixed in all future releases. :)

[upvest-juha]

That seems to just cut the long field and add ellipsis in the end. It doesn't really help in having that long documentation bit in the description field then does it? @EricWittmann

[upvest-juha]

It should really be as long as it needs be per content.

[kilahm]

@upvest-juha - I don't think it should allowed to be arbitrarily long because the artifact and version descriptions are rendered in the registry UI on the artifact list view and the artifact version detail view. The full contents of the OpenAPI document remain as the artifact content, allowing swagger-ui or ReDoc to render the full description.

One more point here: the registry UI doesn't render markdown, so even if the registry accepted the full description from your swagger-ui rendering, the registry wouldn't have the pretty headings or tables.

I see the "description" field of the artifact and version as more like a "summary" rather than a full blown description of the api that the artifact defines.

BTW, I just ran into this issue myself because some teams at my company include fairly extensive general prose in the info.description field. I attempted to work around the issue by altering the description in the OpenAPI document to create the artifact, then changing the description in the document back. This didn't work because the description in the OpenAPI document is always used as the description of the version, limited to 1024. I guess I'll have to wait for this change to ship in a new version. Just saw it's included in 2.0.1.Final.

@EricWittmann - would you be open to perhaps performing the truncation of the description on the UI side instead of in the DB? I could envision someone using the API to fetch the artifact description for incorporation into another tool (such as a developer portal using https://backstage.io/)

[EricWittmann]

@kilahm and/or @upvest-juha Can one of you add this as a new GH issue so I can flag it as a feature request and we can discuss it there? We'll need to consider the ramifications of an unbounded description field.