An OpenAPI utility for Go. This project aims to bring support of OpenAPI v3.
$ gopenapi [command] [arg]gopenapi generate spec [optional path] [flags][optional path] Optionally specify the directory in which to search. Accepts absolute paths. Relative paths are relative to the current directory. (default ".")-f, --format string The format of the output. May be json or yaml (default "json")
-o, --output string Where the output should be directed. May be '-' (stdout) or a path to a file (default "-")Code is annotated with different types of comments that help generate the spec.
The comment contains a keyword that specifies the type of the OpenAPI element.
The content of the comment should be a valid YAML OpenAPI element
Begin a comment with gopenapi:info and follow up with a YAML representation of the OpenAPI Info element.
This element is then set to the info property of the specification.
package main
/*gopenapi:infotitle: The App Nameversion: 1.0description: |- The app descriptioncontact: name: Jimbob Jones url: https://jones.com email: jimbob@jones.comlicense: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html*/funcmain() {
}Begin a comment with gopenapi:path and follow up with a YAML representation of the OpenAPI PathItem element.
This element is then appended to the paths property of the specification.
package main
/*gopenapi:path/ping: get: responses: 200: description: |- The default response of "ping" content: text/plain: example: pong*/funcControllerFunc() {
}Annotate a struct with a gopenapi:objectSchema.
The generated ObjectSchema element will be appended to the components.schemas property of the specification.
//gopenapi:objectSchematypeRootModelstruct {
IntFieldint64`json:"intField"`StringFieldstring`json:"stringField"`
}
// This struct will be ignoredtypeIgnoredModelstruct {
}
//gopenapi:objectSchematypeAliasedModels []*AliasedModel// This alias will appear as a schema too//gopenapi:objectSchematypeAliasedModelstruct {
IgnoredFieldstring`json:"-"`// This field will be ignoredTimeField time.Time
}Annotate a const or a var with a gopenapi:parameter.
The annotated field will be appended to the components.parameters property of the specification.
/*gopenapi:parameterin: pathrequired: truecontent: text/plain: example: 30*/constLimit="limit"The name of the field (Limit) will be the parameter identifier and the value of the field (limit) will be the name of the parameter.