# How to generate swagger specs ## 1. swaggo/swag (current annotations are in this format) * Install [swag](https://github.com/swaggo/swag#getting-started) ``` $ go install github.com/swaggo/swag/cmd/swag@latest ``` * Execute the script at project root to generate swagger specs ``` $ sh ./prepare-swagger-docs.sh ``` ## 2. go-swagger (maybe future option) * Install [go-swagger](https://goswagger.io/install.html) ``` $ brew tap go-swagger/go-swagger $ brew install go-swagger ``` * Execute the script at project root to generate swagger specs ``` $ swagger generate spec -o ./docs/dist/swagger.yaml --scan-models ``` --- # Serve Swagger UI using Firebase hosting 1. Prepare Swagger-UI from [Swagger-UI#unpkg](https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/installation.md#unpkg) in ./docs/dist/index.html index.html ```htmlmixed <!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="description" content="SwaggerUI" /> <title>Ultron DMP API</title> <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui.css" /> </head> <body> <div id="swagger-ui"></div> <script src="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui-bundle.js" crossorigin></script> <script src="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui-standalone-preset.js" crossorigin></script> <script> window.onload = () => { window.ui = SwaggerUIBundle({ url: './swagger.yaml', // generated swagger spec file here dom_id: '#swagger-ui', presets: [ SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset ], layout: "StandaloneLayout", }); }; </script> </body> </html> ``` 2. preview swagger doc throught firebase hosting emulators in directory "./docs/" ``` $ cd docs && firebase emulators:start --only hosting ``` 3. To Update swagger on firebase hosting: ``` $ firebase deploy --only hosting:beta-doraemon-swagger ``` --- ## Speed up swagger annotation using GoLand Live templates: with customized abbr. example: swaggoall ``` // $ComponentName$ // @tags $Tags$ // @Summary $Summary$ // @Description $Description$ // @Accept json // @Produce json // @Param body body $ComponentName$Request true "Body" // @Success 200 {object} $ComponentName$Response // @Failure 400 {string} Bad Request // @Failure 401 {string} Unauthorized // @Security ApiKeyAuth // @Router $ServicePath$$ComponentName$$Postfix$ [post] //@name $ComponentName$Request //@name $ComponentName$Response ``` 如下圖： ![](https://i.imgur.com/nzfHYqq.png) ![](https://i.imgur.com/HqtTtNl.png) move 1. ` //@name $ComponentName$Request` to the closing bracket of RequstBody 2. ` //@name $ComponentName$Response` to the closing bracket of ResponseBody ![](https://i.imgur.com/s49CuPR.png) Swagger UI result from the example above: ![](https://i.imgur.com/SU0r0HZ.png)