Skip to content

About

Default net/http wrapper to automatically generate RESTful API documentation with Swagger

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

9 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

http-swagger

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.

GoDoc Release

Usage

Start using it

  1. Add comments to your API source code, See Declarative Comments Format.
  2. Download Swag for Go by using:
go install github.com/venosm/swag/cmd/swag@latest

To build from source you need Go (1.25 or newer).

Or download a pre-compiled binary from the release page.

  1. Run the Swag in your Go project root folder which contains main.go file, Swag will parse comments and generate required files(docs folder and docs/doc.go).
swag init
  1. Download http-swagger by using:
go get -u github.com/venosm/http-swagger
go get -u github.com/venosm/swag-files # swaggo files

Import following in your code:

import "github.com/venosm/http-swagger" // http-swagger middleware

Canonical example

Now 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:

go-chi

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))
}

OpenAPI 3.0 with go-chi

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))
}
  1. Run it, and browse to http://localhost:1323/swagger/index.html, you can see Swagger 3.0 Api documents.

Configuration

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

License

MIT

About

Default net/http wrapper to automatically generate RESTful API documentation with Swagger

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

⌂ 换网址