From 92cfa4c8ef86e40f538ceb317196afcb15328572 Mon Sep 17 00:00:00 2001 From: Xieyuschen Date: Sat, 25 Sep 2021 05:25:27 +0800 Subject: [PATCH] Edit readme to makes it more friendly to newer (#132) * edit readme to makes it more friendly to newer * Fix for reviewing * Fix comment format Co-authored-by: Xieyuschen --- README.md | 155 +++++++++++++++++++++++++++++------------------------- 1 file changed, 83 insertions(+), 72 deletions(-) diff --git a/README.md b/README.md index 6b7c880..918702f 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # gin-swagger -gin middleware to automatically generate RESTful API documentation with Swagger 2.0. +gin middleware to automatically generate RESTFUL API documentation with Swagger 2.0. [![Build Status](https://github.com/swaggo/gin-swagger/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/features/actions) [![Codecov branch](https://img.shields.io/codecov/c/github/swaggo/gin-swagger/master.svg)](https://codecov.io/gh/swaggo/gin-swagger) @@ -14,19 +14,21 @@ gin middleware to automatically generate RESTful API documentation with Swagger 1. Add comments to your API source code, [See Declarative Comments Format](https://swaggo.github.io/swaggo.io/declarative_comments_format/). 2. Download [Swag](https://github.com/swaggo/swag) for Go by using: ```sh -$ go get -u github.com/swaggo/swag/cmd/swag +go get -u github.com/swaggo/swag/cmd/swag ``` -3. Run the [Swag](https://github.com/swaggo/swag) in your Go project root folder which contains `main.go` file, [Swag](https://github.com/swaggo/swag) will parse comments and generate required files(`docs` folder and `docs/doc.go`). +3. Run the [Swag](https://github.com/swaggo/swag) at your Go project root path(for instance `~/root/go-peoject-name`), + [Swag](https://github.com/swaggo/swag) will parse comments and generate required files(`docs` folder and `docs/doc.go`) + at `~/root/go-peoject-name/docs`. ```sh -$ swag init +swag init ``` 4. Download [gin-swagger](https://github.com/swaggo/gin-swagger) by using: ```sh -$ go get -u github.com/swaggo/gin-swagger -$ go get -u github.com/swaggo/files +go get -u github.com/swaggo/gin-swagger +go get -u github.com/swaggo/files ``` -And import following in your code: +Import following in your code: ```go import "github.com/swaggo/gin-swagger" // gin-swagger middleware @@ -35,84 +37,93 @@ import "github.com/swaggo/files" // swagger embed files ``` ### Canonical example: - +Now assume you have implemented a simple api as following: ```go -package main - -import ( - "github.com/gin-gonic/gin" - swaggerFiles "github.com/swaggo/files" - ginSwagger "github.com/swaggo/gin-swagger" - - _ "github.com/swaggo/gin-swagger/example/basic/docs" // docs is generated by Swag CLI, you have to import it. -) - -// @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 := gin.New() +// A get function which returns a hello world string by json +func Helloworld(g *gin.Context) { + g.JSON(http.StatusOK,"helloworld") +} - url := ginSwagger.URL("http://localhost:8080/swagger/doc.json") // The url pointing to API definition - r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url)) +``` +So how to use gin-swagger on api above? Just follow the following guide. - r.Run() +1. Add Comments for apis and main function with gin-swagger rules like following: +```go +// @BasePath /api/v1 + +// PingExample godoc +// @Summary ping example +// @Schemes +// @Description do ping +// @Tags example +// @Accept json +// @Produce json +// @Success 200 {string} Helloworld +// @Router /example/helloworld [get] +func Helloworld(g *gin.Context) { + g.JSON(http.StatusOK,"helloworld") } ``` -5. Run it, and browse to http://localhost:8080/swagger/index.html, you can see Swagger 2.0 Api documents. - -![swagger_index.html](https://user-images.githubusercontent.com/8943871/60704329-b7ab0680-9f36-11e9-9184-5c638c05e9c5.png) - -6. If you want to disable swagger when some environment variable is set, use `DisablingWrapHandler` - -### Example with disabling: +2. Use `swag init` command to generate a docs, docs generated will be stored at +3. import the docs like this: + I assume your project named `github.com/go-project-name/docs`. +```go +import ( + docs "github.com/go-project-name/docs" +) +``` +4. build your application and after that, go to http://localhost:8080/swagger/index.html ,you to see your Swagger UI. +5. The full code and folder relatives here: ```go package main import ( - "github.com/gin-gonic/gin" - swaggerFiles "github.com/swaggo/files" - ginSwagger "github.com/swaggo/gin-swagger" - - _ "github.com/swaggo/gin-swagger/example/basic/docs" // docs is generated by Swag CLI, you have to import it. + "github.com/gin-gonic/gin" + docs "github.com/go-project-name/docs" + swaggerfiles "github.com/swaggo/files" + ginSwagger "github.com/swaggo/gin-swagger" + "net/http" ) +// @BasePath /api/v1 + +// PingExample godoc +// @Summary ping example +// @Schemes +// @Description do ping +// @Tags example +// @Accept json +// @Produce json +// @Success 200 {string} Helloworld +// @Router /example/helloworld [get] +func Helloworld(g *gin.Context) { + g.JSON(http.StatusOK,"helloworld") +} -// @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 := gin.New() - - // use ginSwagger middleware to - r.GET("/swagger/*any", ginSwagger.DisablingWrapHandler(swaggerFiles.Handler, "NAME_OF_ENV_VARIABLE")) +func main() { + r := gin.Default() + docs.SwaggerInfo.BasePath = "/api/v1" + v1 := r.Group("/api/v1") + { + eg := v1.Group("/example") + { + eg.GET("/helloworld",Helloworld) + } + } + r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler)) + r.Run(":8080") - r.Run() } ``` - -Then, if you set environment variable `NAME_OF_ENV_VARIABLE` to anything, `/swagger/*any` -will respond 404, just like when route unspecified. +Demo project tree, `swag init` is run at relative `.` +``` +. +├── docs +│   ├── docs.go +│   ├── swagger.json +│   └── swagger.yaml +├── go.mod +├── go.sum +└── main.go +``` \ No newline at end of file