Could this support swagger3.0?
Generate Swagger documentation server in Go from Swagger/OpenAPI specification - Stack Overflow
go - Generate OpenAPI spec from gin project - Stack Overflow
Support OpenAPI 3.1
I have been using https://github.com/swaggo/swag with https://github.com/swaggo/gin-swagger.
Very nice work done there. But I think that project is way behind. OpenAPI v3 has been there for a long time. Are there any similar project which can generate swagger.(yaml|json) based on comments like gin-swagger does?
I am not sure about Gin, but I am happy to share my solution (based upon go-server):
- Create a directory in your project root dir called ./swagger-ui
- Copy the files under
dist/*of swagger-ui (https://github.com/swagger-api/swagger-ui/tree/master/dist) here - Update in
swagger-ui/index.htmlthe location of the api spec tourl: "/api/openapi.yaml" - In
main.gocreate a new variable annotated with//go:embed swagger-ui/* api/openapi.yaml(the latter directory was created by openapi-generator CLI) - Add below the (generated) router in
main.go:router.PathPrefix("/").Handler(http.FileServer(http.FS(staticFiles)))
That's it - you will have the Swagger UI available under /swagger-ui and the api definition loaded automatically from /api/openapi.yaml
package main
import (
"context"
...
)
//go:embed swagger-ui/* api/openapi.yaml
var staticFiles embed.FS
func main() {
router := ....
// Embed the Swagger UI within Go binary
router.PathPrefix("/").Handler(http.FileServer(http.FS(staticFiles)))
...
There is a library that packages Swagger UI as Go http.Handler: https://github.com/swaggest/swgui.
package main
import (
"net/http"
"github.com/swaggest/swgui/v3emb" // For go1.16 or later.
// "github.com/swaggest/swgui/v3" // For go1.15 and below.
)
func main() {
http.Handle("/", v3.NewHandler("My API", "/swagger.json", "/"))
http.ListenAndServe(":8080", nil)
}
"/swagger.json" in this example is an URL to the OpenAPI spec file.
gin-swagger is extracting comments from your code.
Running swag init generates :
- docs.go: To serve SwaggerUI pages
- swagger.json: The Swagger Specification in json file format.
- swagger.yaml: The Swagger Specification in yaml file format.
You mean API docs for API user?
I saw you tag the question with swagger.
You have two chooses:
- go-swagger
This package contains a golang implementation of Swagger 2.0 (aka OpenAPI 2.0): it knows how to serialize and deserialize swagger specifications.
- swag
Swag converts Go annotations to Swagger Documentation 2.0. We've created a variety of plugins for popular Go web frameworks. This allows you to quickly integrate with an existing Go project (using Swagger UI).
What difference between them?
Here is the answer from go-swagger:
The main difference at this moment is that this one actually works...
The swagger-codegen project (like
swag) only generates a workable go client and even there it will only support flat models. Further, the go server generated by swagger-codegen is mostly a stub.
Detail of this answer in How is this different from go generator in swagger-codegen? from go-swagger.
Hi,
I would like to automate the generation of an openapi document based on routes and functions defined for go gin.
There are some derivates already like swag and go-swagger, but things that bother me with both are that its only openapi 2.0, and the fact that it is based on annotations/comment on the actual functions.
Would it be possible in general to create a generator that is not based on annotations? Like via reflection somehow inspecting the router and its routes, middlewares and handler functions in regards to inputs, return types and potential error codes?
Not exactly sure, if possible at all. Thanks in advance!
Hi Friends
I am using gin-swagger to write comments in Go code and automatically generate Open API/Swagger documentation for the REST service exposed externally through these comments.
gin-swagger is just a top-level shell, and the actual work is done by another framework called swag, https://github.com/swaggo/swag/tree/master
A type is defined as follows:
```go
package middleware
type Response struct {
...other fields omitted...
data any
}
```
Add the following comments for the HTTP method in the Controller:
```go
// @Success 200 {object} middleware.Response
// @Success 500 {object} middleware.Response
```
After executing the `swag init`, the OpenAPI was correctly generated, although the result was not what I expected.
To get the expected result, I added a generic type argument to the Response struct:
```go
type Response[T any] struct {
...other fields omitted...
data T
}
```
Then I modified the comments in the HTTP function of the Controller:
```go
// @Success 200 {object} middleware.Response[int]
// @Success 500 {object} middleware.Response[string]
```
After executing the command again to regenerating the OpenAPI, an error occurred: "cannot find type definition".
The swag documentation clearly states that it supports Go generics, and the documentation for this feature can be found [here](https://github.com/swaggo/swag/tree/master?tab=readme-ov-file#how-to-use-generics)
As you can see, the framework explicitly states that it supports this feature, and the usage shown in its documentation is completely consistent with mine.
Finally, when searching for this issue, several issues occurred during the period when Go added generics, and the problems were caused by the users using versions of the frameworks that were too old. However, my version is the latest v1.16.3, which is far beyond the required version for this feature, yet the problem still persists.
Has anyone encountered this issue before?