search

swaggo / swag

Automatically generate RESTful API documentation with Swagger 2.0 for Go.
MIT License
10.46k stars 1.19k forks source link

Annotation Extensions for Documenting Multiple Response Formats #1760

Open kaptinlin opened 6 months ago

kaptinlin commented 6 months ago

Is your feature request related to a problem? Please describe.

Yes, the problem arises when trying to document API endpoints that are capable of returning multiple response formats based on the request's Accept header or specific query parameters. Currently, swag does not offer a straightforward way to annotate a single API endpoint to document these multiple potential response formats. This limitation leads to less accurate and comprehensive API documentation. For instance, I find it frustrating when I have an endpoint that can return data in either JSON or CSV format, but I'm unable to document both response types accurately using swag annotations. This forces me to choose a single response format for documentation or resort to external documentation methods to convey the full capabilities of the endpoint.

Describe the solution you'd like

I would like swag to support enhanced annotation capabilities that allow documenting multiple response formats for a single API endpoint. Specifically, the solution should include:

  1. Multiple @Success and @Failure Annotations: Allow these annotations to be specified multiple times for the same HTTP status code but with different Produce fields to document the different MIME types an endpoint can produce.

  2. Introduction of a Produce Field in Response Annotations: This field would specify the MIME type of the response. It would be used alongside the current fields in @Success and @Failure annotations to link the documented response format directly with its MIME type.

Example Annotation with Proposed Changes:

// @Success 200 {object} YourJsonResponseModel "Successfully retrieved the article in JSON format." Produce(application/json)
// @Success 200 {string} string "Successfully retrieved the article in CSV format." Produce(text/csv)

This enhancement would allow developers to accurately document the full range of an API endpoint's capabilities directly within their code, improving the clarity and utility of the generated API documentation.

Additional context

The ability to return different response formats from a single API endpoint is a common requirement for modern web services, catering to various client needs and preferences. Enhancing swag to support documenting these capabilities directly in code annotations would significantly improve the tool's utility and the quality of the generated documentation. This feature would make swag a more comprehensive tool for documenting complex APIs, ultimately benefiting developers and API consumers alike by providing clearer, more accurate, and more accessible API documentation.

sdghchj commented 6 months ago

It seems your proposal is at presentation level.

Refer to operationObject , one status code with one schema.