forked from swaggo/gin-swagger
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Edit readme to makes it more friendly to newer (swaggo#132)
* edit readme to makes it more friendly to newer * Fix for reviewing * Fix comment format Co-authored-by: Xieyuschen <[email protected]>
- Loading branch information
1 parent
f617c81
commit 92cfa4c
Showing
1 changed file
with
83 additions
and
72 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. | ||
|
|
||
| [](https://github.com/features/actions) | ||
| [](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 [email protected] | ||
|
|
||
| // @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. | ||
|
|
||
|  | ||
|
|
||
| 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 [email protected] | ||
|
|
||
| // @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 | ||
| ``` | ||