This project is based on http-swagger with enhanced features and improvements.
Default net/http wrapper to automatically generate RESTful API documentation with Swagger 3.0.
- Add comments to your API source code, See Declarative Comments Format.
- Download Swag for Go by using:
go install github.com/venosm/swag/cmd/swag@latestTo build from source you need Go (1.25 or newer).
Or download a pre-compiled binary from the release page.
- Run the Swag in your Go project root folder which contains
main.gofile, Swag will parse comments and generate required files(docsfolder anddocs/doc.go).
swag init- Download http-swagger by using:
go get -u github.com/venosm/http-swagger
go get -u github.com/venosm/swag-files # swaggo filesImport following in your code:
import "github.com/venosm/http-swagger" // http-swagger middlewareNow assume you have implemented a simple api as following:
// A get function which can be called as a REST API endpoint.
// @Summary Show an account
// @Description get string by ID
// @ID get-string-by-int
// @Accept json
// @Produce json
// @Param id path int true "Account ID"
// @Success 200 {object} model.Account
// @Failure 400 {object} httputil.HTTPError
// @Failure 404 {object} httputil.HTTPError
// @Failure 500 {object} httputil.HTTPError
// @Router /accounts/{id} [get]
func (c *Controller) ShowAccount(w http.ResponseWriter, r *http.Request) {
// your code here
}So how to use http-swagger on famous frameworks:
Please refer to the example folder
package main
import (
"log"
"net/http"
"github.com/go-chi/chi"
_ "github.com/venosm/http-swagger/example/go-chi/docs" // docs is generated by Swag CLI, you have to import it.
httpSwagger "github.com/venosm/http-swagger"
)
// @title Swagger Example API
// @version 1.0
// @description This is a sample server Petstore server.
// @termsOfService http://swagger.io/terms/
// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io
// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
// @host petstore.swagger.io
// @BasePath /v2
func main() {
r := chi.NewRouter()
r.Get("/swagger/*", httpSwagger.Handler(
httpSwagger.URL("http://localhost:1323/swagger/doc.json"), //The url pointing to API definition
))
log.Fatal(http.ListenAndServe(":1323", r))
}Please refer to the example folder
package main
import (
"log"
"net/http"
"github.com/go-chi/chi/v5"
_ "github.com/venosm/http-swagger/example/openapi3-go-chi/docs" // docs is generated by Swag CLI, you have to import it.
httpSwagger "github.com/venosm/http-swagger"
)
// @title OpenAPI 3.0 Example API
// @version 1.0.0
// @description This is a sample server demonstrating OpenAPI 3.0 support.
// @termsOfService http://swagger.io/terms/
// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io
// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
// @host petstore.swagger.io
// @BasePath /v3
func main() {
r := chi.NewRouter()
r.Get("/swagger/*", httpSwagger.Handler(
httpSwagger.URL("http://localhost:1323/swagger/openapi.json"), // The url pointing to API definition
httpSwagger.TryItOutEnabled(true), // Enable "Try it out" for OpenAPI 3.0
httpSwagger.DefaultModelsExpandDepth(1),
httpSwagger.ShowExtensions(true),
))
log.Println("Server starting on :1323")
log.Fatal(http.ListenAndServe(":1323", r))
}- Run it, and browse to http://localhost:1323/swagger/index.html, you can see Swagger 3.0 Api documents.
You can configure Swagger using different configuration options
func Handler(c ...Config) http.HandlerFunc| Option | Type | Default | Description |
|---|---|---|---|
| URL | string | "doc.json" | URL pointing to the API definition |
| DocExpansion | string | "list" | Controls the default expansion setting for the operations and tags |
| DomID | string | "#swagger-ui" | Controls the default domID |
| InstanceName | string | "swagger" | The instance name of the swagger document |
| DeepLinking | bool | true | Controls whether deep linking is enabled |
| PersistAuthorization | bool | false | Controls whether authorization data is persisted |