{ "slug": "Make-swagger-from-your-HTTP-Rest-full-in-Golang-4dc9088f5292", "title": "Make swagger from your HTTP Rest full in Golang", "subtitle": "One of the best tools for document Backend API is Swagger. And also can send data at the endpoint easily with no other tools. In this…", "excerpt": "One of the best tools for document Backend API is Swagger. And also can send data at the endpoint easily with no other tools. In this…", "date": "2023-07-12", "tags": [ "My Experience", "Go", "API" ], "readingTime": "2 min", "url": "https://medium.com/@mobinshaterian/make-swagger-from-your-http-rest-full-in-golang-4dc9088f5292", "hero": "https://cdn-images-1.medium.com/max/800/1*buhBlXQFqXqc3DjEP2ueZA.png", "content": [ { "type": "heading", "level": 2, "text": "Make swagger from your HTTP Rest full in Golang" }, { "type": "paragraph", "html": "One of the best tools for document Backend API is Swagger. And also can send data at the endpoint easily with no other tools. In this article, we will set up Swagger for restful API for Golang." }, { "type": "paragraph", "html": "Golang has powerful as GRPC to swagger. But I didn’t use it in the current project. Anyway, converting GRPC to HTTP and making Swagger automatically with this project is possible." }, { "type": "image", "src": "https://cdn-images-1.medium.com/max/800/1*buhBlXQFqXqc3DjEP2ueZA.png", "alt": "https://swagger.io/tools/swagger-ui/", "caption": "https://swagger.io/tools/swagger-ui/", "width": 740, "height": 423 }, { "type": "heading", "level": 2, "text": "Install Swagger Golang package" }, { "type": "paragraph", "html": "The Swaggo is one of the best libraries that can make Swagger for HTTP server requests. It supports many HTTP libraries in Golang, such as:" }, { "type": "list", "ordered": false, "items": [ "gin", "echo", "buffalo", "net/http", "gorilla/mux", "go-chi/chi", "flamingo", "fiber", "atreugo", "hertz" ] }, { "type": "paragraph", "html": "In this article I going to explain about the net/http, one can easily with below link." }, { "type": "code", "lang": "text", "code": "https://github.com/swaggo/http-swagger" }, { "type": "heading", "level": 2, "text": "Install Swagger with Golang" }, { "type": "code", "lang": "bash", "code": "go install github.com/swaggo/swag/cmd/swag@latestswag init" }, { "type": "heading", "level": 2, "text": "Initial Swagger" }, { "type": "code", "lang": "go", "code": "//\n@title title//\n@version 2.0//\n@description This is a sample server corepass server.//\n@termsOfService http://swagger.io/terms///\n@contact.name API Support//\n@contact.url http://www.swagger.io/support//\n@contact.email support@swagger.io//\n@license.name Apache 2.0//\n@license.url http://www.apache.org/licenses/LICENSE-2.0.html//\n@query.collection.format multi//\n@securityDefinitions.basic BasicAuth//\n@externalDocs.description OpenAPI//\n@externalDocs.url https://swagger.io/resources/open-api/\nfunc InitialSwagger() {\n // programmatically set swagger info // docs.SwaggerInfo.Host = config.ServerHttpAddress()\n docs.SwaggerInfo.Schemes = []string{\n \"https\", \"http\"\n }\n r := mux.NewRouter()\n r.PathPrefix(\"/swagger/\").Handler(httpSwagger.Handler(httpSwagger.URL(\"/swagger/doc.json\"),\n //The url pointing to API definition httpSwagger.DeepLinking(true),\n httpSwagger.DocExpansion(\"none\"), httpSwagger.DomID(\"swagger-ui\"),)).Methods(http.MethodGet) go\n http.ListenAndServe(config.SwaggerUrl(), r) logger.Info(\"Swagger Server Server : \",\n config.SwaggerUrl())\n}" }, { "type": "heading", "level": 2, "text": "Example of install swagger" }, { "type": "heading", "level": 2, "text": "Write swagger for show in the router" }, { "type": "paragraph", "html": "Every endpoint need detail of of endpoint." }, { "type": "code", "lang": "go", "code": "// ShowAccount godoc// @Summary Show an account// @Description get string by ID// @Tags\naccounts// @Accept json// @Produce json// @Param id path int true\n\"Account ID\"// @Success 200 {object} model.Account// @Failure 400 {object}\nhttputil.HTTPError// @Failure 404 {object} httputil.HTTPError// @Failure 500 {object}\nhttputil.HTTPError// @Router /accounts/{id} [get]" }, { "type": "heading", "level": 2, "text": "Attribute" }, { "type": "code", "lang": "go", "code": "// @Param enumstring query string false \"string enums\" Enums(A, B, C)// @Param\nenumint query int false \"int enums\" Enums(1, 2, 3)// @Param enumnumber\nquery number false \"int enums\" Enums(1.1, 1.2, 1.3)// @Param string query\nstring false \"string valid\" minlength(5) maxlength(10)// @Param int query\nint false \"int valid\" minimum(1) maximum(10)// @Param default query\nstring false \"string default\" default(A)// @Param example query string false\n\"string example\" example(string)// @Param collection query []string false\n\"string collection\" collectionFormat(multi)// @Param extensions query []string false\n\"string collection\" extensions(x-example=test,x-nullable)" }, { "type": "heading", "level": 2, "text": "Good Examples that wrote in their repository" }, { "type": "code", "lang": "text", "code": "https://github.com/swaggo/swag/blob/master/example/basic/api/api.go" }, { "type": "heading", "level": 2, "text": "Param Type" }, { "type": "list", "ordered": false, "items": [ "query", "path", "header", "body", "formData" ] }, { "type": "heading", "level": 2, "text": "Command for run Swagger" }, { "type": "code", "lang": "text", "code": "swag init -g path/router.gofor example :swag init -g app/router/router.go" } ] }