Menu
I just started working on Swagger 2.0 API recently. I am looking for some ways to organize the API documentation.
Currently I'm using the @Api(tags = {"Heading1"}) Java annotation to tag each API. The generated documentation looks like
Tasks
--------->Heading1
-------->Desc1
--------->Desc2
---------->Heading2
--------->Desc3
--------->Desc4
I'd like to add some subheadings in the doc, so that it looks like
Tasks
--------->Heading1
-------->Desc1
--------->SubHeading1
--------->Desc2
---------->Heading2
--------->SubHeading1
--------->Desc3
--------->SubHeading1
--------->Desc4
How do I achieve this?
343
You can assign a list of tags to each API operation. Tagged operations may be handled differently by tools and libraries. For example, Swagger UI uses tags to group the displayed operations. Optionally, you can specify description and externalDocs for each tag by using the global tags section on the root level.
The tags object allows you to arrange the paths (endpoints) into named groups in the Swagger UI display.
The Springfox library provides @Api annotation to configure a class as a Swagger resource. Previously, the @Api annotation provided a description attribute to customize the API documentation: @Api(value = "", description = "") However, as mentioned earlier, the description attribute is deprecated.
Multiple hosts are supported in OpenAPI 3.0. 2.0 supports only one host per API specification (or two if you count HTTP and HTTPS as different hosts). A possible way to target multiple hosts is to omit the host and schema from your specification and serve it from each host.
Nested tags are not supported by the OpenAPI Specification. Here's the corresponding feature request:
https://github.com/OAI/OpenAPI-Specification/issues/1367
You can try to emulate nested tags by naming your tags tag1/tag2, tag1.tag2, tag1|tag2 or similar, but then you'd also have to modify your tools to handle such names as nested tags.
Note for Swagger UI users: There's a feature request to support nested tags using tag names in the form tag1|tag2 or similar:
https://github.com/swagger-api/swagger-ui/issues/5969
57
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
