search

swaggo / swag

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

externalDocs not implemented #470

Open pjebs opened 5 years ago

pjebs commented 5 years ago

externalDocs

Field Name Type Description
tags [string] A list of tags for API documentation control. Tags can be used for logical grouping of operations by resources or any other qualifier.
summary string A short summary of what the operation does.
description string A verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation.
externalDocs External Documentation Object Additional external documentation for this operation.
operationId string Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is case-sensitive. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.
ubogdan commented 5 years ago

Please follow bug report template and provide steps to reproduce.

pjebs commented 5 years ago

It's not a bug. It's a feature request. Swagger 2 format allows for another field called: externalDocs which isn't implemented.

The table above is directly from the swagger docs.

ubogdan commented 5 years ago

There are @tag.docs.url and "@tag.docs.description":

tag.docs.url Url of the external Documentation of the tag // @tag.docs.url https://example.com
tag.docs.descripiton Description of the external Documentation of the tag // @tag.docs.descirption Best example documentation
admPiett commented 4 years ago

tag.docs.* seems to be for General API Info, not for API Operation. The operation spec has an ExternalDocs field that could be set.

brockoffdev commented 3 years ago

I would like to see this reopened, as well. May make a PR for it. Could be useful for myself and our team.