search

swagger-api / swagger-ui

Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.
https://swagger.io
Apache License 2.0
26.58k stars 8.96k forks source link

Filter out empty API groups (or Tags) #4307

Open erajkovic opened 6 years ago

erajkovic commented 6 years ago

Is there a way to filter content - empty API groups (or Tags) - when displaying content of a Swagger API document with Swagger UI 3 similar to what was done in Swagger UI 2

Q A
Bug or feature request? Not sure if this is a feature request or a support question
Which Swagger/OpenAPI version? Swagger 2.0
Which Swagger-UI version? Swagger UI 3.9.1
How did you install Swagger-UI? using the webjar project
Which browser & version? Chrome 64.0.3282.186
Which operating system? Mac OS-X 10.13.3

Demonstration API definition

Is there a way to filter out the empty APIs groups in Swagger UI 3, the same way it was done on the older version?

see the data we have now, with nothing to drill-down into

Calculate Shipping | Webhook for calculating shipping cost External Pricing | This event is triggered at ‘add to cart’ page requesting validation of external pricing details for products with external prices External Tax Calculation | This event is triggered at checkout page to get tax for cart from external service ...

Test links: https://apicatalog.oraclecloud.com/ui/views/swaggerui3/oracle-public/commerce/17.4/webhooks?urls.primaryName=Webhooks vs. https://apicatalog.oraclecloud.com/ui/views/apicollection/oracle-public/commerce/17.4/webhooks

Expected Behavior

By default, it would be nice to hide empty content, so that we can focus on the part of the APIs that does have content. An alternative option would be to add a configuration parameter if you like seeing empty content for some other use case.

Current Behavior

List all the Tags, even when they have no associated content.

Possible Solution

Context

Trying to migrate our API Catalog from using Swagger 2.0 to the latest version of OpenApi 3.0 / Swagger UI 3.x

hkosova commented 6 years ago

See https://github.com/swagger-api/swagger-ui/issues/4157#issuecomment-363917366

erajkovic commented 6 years ago

Maybe it's a duplicate of #3819 - I can see two scenario where we have empty groups: a) when the declaration and reference are not inline - "Webhooks/Organization" vs. "Organization" b) when you want to split a larger set of APIs, and you use the superset of tags across your openapi specs. While I agree that the data can be fixed, it does not look good for existing specs that are already rendered in older versions.

webron commented 6 years ago

@erajkovic this is not a feature I'd be excited to implement, but you bring up a fair point about migrating from an older version, and we do want to make it easy for our users. Let us think about it for a bit before we proceed.