Skip to content

Commit 2af46aa

Browse files
pei0804easonlin404
pei0804
authored and
easonlin404
committed
Add security doc and update main README. (#3)
1 parent d05a8a0 commit 2af46aa

File tree

6 files changed

+251
-14
lines changed

6 files changed

+251
-14
lines changed

‎.travis.yml

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,11 @@ node_js:
33
- '7'
44
sudo: false
55
script:
6-
- sudo -v && wget -nv -O- https://raw.githubusercontent.com/kovidgoyal/calibre/master/setup/linux-installer.py | sudo python -c "import sys; main=lambda:sys.stderr.write('Download failed\n'); exec(sys.stdin.read()); main()"
7-
- sudo ln -s /opt/calibre/ebook-convert /usr/local/bin/
8-
- make install
9-
- make publish
6+
- $TRAVIS_BRANCH == "master" && $TRAVIS_PULL_REQUEST == "false" && make travis-deploy
107
before_install:
118
- openssl aes-256-cbc -K $encrypted_e8c0cd5f9239_key -iv $encrypted_e8c0cd5f9239_iv -in deploy_key.enc -out deploy_key -d
129
- chmod 600 deploy_key
1310
- eval `ssh-agent -s`
1411
- ssh-add deploy_key
1512
- git config --global user.name "publisher"
1613
- git config --global user.email "[email protected]"
17-
branches:
18-
only:
19-
- master

‎Makefile

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
SHELL := /bin/bash
22

3-
.PHONY: all install prepare build watch publish pdf epub mobi clean
3+
.PHONY: all install prepare build watch publish pdf epub mobi clean travis-deploy
44

55
all: install build
66

@@ -42,3 +42,9 @@ clean:
4242
rm -rf _book
4343
rm -rf node_modules
4444

45+
travis-deploy:
46+
sudo -v && wget -nv -O- https://raw.githubusercontent.com/kovidgoyal/calibre/master/setup/linux-installer.py | sudo python -c "import sys; main=lambda:sys.stderr.write('Download failed\n'); exec(sys.stdin.read()); main()"
47+
sudo ln -s /opt/calibre/ebook-convert /usr/local/bin/
48+
$(MAKE) install
49+
$(MAKE) publish
50+

‎README.md

Lines changed: 200 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,208 @@
2121
## What is swag?
2222
swag converts Go annotations to Swagger Documentation 2.0. And provides a variety of builtin [web framework](#supported-web-framework) lib. Let you can quickly integrated in existing golang project(using Swagger UI) .
2323

24-
## Documentation
24+
## Status of implementations
25+
26+
[Swagger 2.0 document](https://swagger.io/docs/specification/2-0/basic-structure/)
27+
28+
- [x] Basic Structure
29+
- [x] API Host and Base Path
30+
- [x] Paths and Operations
31+
- [x] Describing Parameters
32+
- [x] Describing Request Body
33+
- [x] Describing Responses
34+
- [x] MIME Types
35+
- [x] Authentication
36+
- [x] Basic Authentication
37+
- [x] API Keys
38+
- [x] Adding Examples
39+
- [x] File Upload
40+
- [ ] Enums
41+
- [x] Grouping Operations With Tags
42+
- [ ] Swagger Extensions
43+
44+
## Document
2545

2646
- [web](https://swaggo.github.io/swaggo.io/)
2747
- [pdf](https://github.com/swaggo/swaggo.io/raw/gh-pages/swaggo.pdf)
2848
- [epub](https://github.com/swaggo/swaggo.io/raw/gh-pages/swaggo.epub)
2949
- [mobi](https://github.com/swaggo/swaggo.io/raw/gh-pages/swaggo.mobi)
50+
51+
## Example
52+
53+
[swaggo + gin](https://github.com/swaggo/swag/tree/master/example/celler)
54+
55+
## Getting started
56+
57+
1. Add comments to your API source code, [See Declarative Comments Format](https://swaggo.github.io/swaggo.io/declarative_comments_format/)
58+
59+
2. Download swag by using:
60+
```sh
61+
$ go get -u github.com/swaggo/swag/cmd/swag
62+
```
63+
3. Run the [swag](#generate-swagger-20-docs) in project root folder which contains `main.go` file, The [swag](#generate-swagger-20-docs) will parse your comments and generate required files(`docs` folder and `docs/doc.go`).
64+
```sh
65+
$ swag init
66+
```
67+
68+
## How to use it with `gin`?
69+
70+
This example source [here.](https://github.com/swaggo/swag/tree/master/example/celler)
71+
72+
1.After using [swag](#generate-swagger-20-docs) to generate Swagger 2.0 docs. Import following packages:
73+
74+
```go
75+
import "github.com/swaggo/gin-swagger" // gin-swagger middleware
76+
import "github.com/swaggo/gin-swagger/swaggerFiles" // swagger embed files
77+
```
78+
79+
***Supported Web Framework in generate swagger middleware***
80+
81+
- [gin](http://github.com/swaggo/gin-swagger)
82+
- [echo](http://github.com/swaggo/echo-swagger)
83+
- [net/http](https://github.com/swaggo/http-swagger)
84+
- revel
85+
86+
2.Added [General API Info](https://swaggo.github.io/swaggo.io/declarative_comments_format/api_operation.html) annotations in `main.go` code:
87+
88+
```go
89+
// @title Swagger Example API
90+
// @version 1.0
91+
// @description This is a sample server celler server.
92+
// @termsOfService http://swagger.io/terms/
93+
94+
// @contact.name API Support
95+
// @contact.url http://www.swagger.io/support
96+
// @contact.email [email protected]
97+
98+
// @license.name Apache 2.0
99+
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
100+
101+
// @host localhost:8080
102+
// @BasePath /api/v1
103+
104+
// @securityDefinitions.basic BasicAuth
105+
106+
// @securityDefinitions.apikey ApiKeyAuth
107+
// @in header
108+
// @name Authorization
109+
110+
// @securitydefinitions.oauth2.application OAuth2Application
111+
// @tokenUrl https://example.com/oauth/token
112+
// @scope.write Grants write access
113+
// @scope.admin Grants read and write access to administrative information
114+
115+
// @securitydefinitions.oauth2.implicit OAuth2Implicit
116+
// @authorizationurl https://example.com/oauth/authorize
117+
// @scope.write Grants write access
118+
// @scope.admin Grants read and write access to administrative information
119+
120+
// @securitydefinitions.oauth2.password OAuth2Password
121+
// @tokenUrl https://example.com/oauth/token
122+
// @scope.read Grants read access
123+
// @scope.write Grants write access
124+
// @scope.admin Grants read and write access to administrative information
125+
126+
// @securitydefinitions.oauth2.accessCode OAuth2AccessCode
127+
// @tokenUrl https://example.com/oauth/token
128+
// @authorizationurl https://example.com/oauth/authorize
129+
// @scope.admin Grants read and write access to administrative information
130+
131+
func main() {
132+
r := gin.Default()
133+
134+
c := controller.NewController()
135+
136+
v1 := r.Group("/api/v1")
137+
{
138+
accounts := v1.Group("/accounts")
139+
{
140+
accounts.GET(":id", c.ShowAccount)
141+
accounts.GET("", c.ListAccounts)
142+
accounts.POST("", c.AddAccount)
143+
accounts.DELETE(":id", c.DeleteAccount)
144+
accounts.PATCH(":id", c.UpdateAccount)
145+
accounts.POST(":id/images", c.UploadAccountImage)
146+
}
147+
//...
148+
}
149+
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
150+
r.Run(":8080")
151+
}
152+
//...
153+
154+
```
155+
156+
3.Added [API Operation](https://swaggo.github.io/swaggo.io/declarative_comments_format/general_api_info.html) annotations in `controller` code
157+
158+
``` go
159+
package controller
160+
161+
import (
162+
"fmt"
163+
"net/http"
164+
"strconv"
165+
166+
"github.com/gin-gonic/gin"
167+
"github.com/swaggo/swag/example/celler/httputil"
168+
"github.com/swaggo/swag/example/celler/model"
169+
)
170+
171+
// ShowAccount godoc
172+
// @Summary Show a account
173+
// @Description get string by ID
174+
// @ID get-string-by-int
175+
// @Accept json
176+
// @Produce json
177+
// @Param id path int true "Account ID"
178+
// @Success 200 {object} model.Account
179+
// @Failure 400 {object} httputil.HTTPError
180+
// @Failure 404 {object} httputil.HTTPError
181+
// @Failure 500 {object} httputil.HTTPError
182+
// @Router /accounts/{id} [get]
183+
func (c *Controller) ShowAccount(ctx *gin.Context) {
184+
id := ctx.Param("id")
185+
aid, err := strconv.Atoi(id)
186+
if err != nil {
187+
httputil.NewError(ctx, http.StatusBadRequest, err)
188+
return
189+
}
190+
account, err := model.AccountOne(aid)
191+
if err != nil {
192+
httputil.NewError(ctx, http.StatusNotFound, err)
193+
return
194+
}
195+
ctx.JSON(http.StatusOK, account)
196+
}
197+
198+
// ListAccounts godoc
199+
// @Summary List accounts
200+
// @Description get accounts
201+
// @Accept json
202+
// @Produce json
203+
// @Param q query string false "name search by q"
204+
// @Success 200 {array} model.Account
205+
// @Failure 400 {object} httputil.HTTPError
206+
// @Failure 404 {object} httputil.HTTPError
207+
// @Failure 500 {object} httputil.HTTPError
208+
// @Router /accounts [get]
209+
func (c *Controller) ListAccounts(ctx *gin.Context) {
210+
q := ctx.Request.URL.Query().Get("q")
211+
accounts, err := model.AccountsAll(q)
212+
if err != nil {
213+
httputil.NewError(ctx, http.StatusNotFound, err)
214+
return
215+
}
216+
ctx.JSON(http.StatusOK, accounts)
217+
}
218+
219+
//...
220+
```
221+
222+
4.Run it, and browser to http://localhost:8080/swagger/index.html. You will see Swagger 2.0 Api documents as bellow:
223+
224+
![swagger_index.html](https://raw.githubusercontent.com/swaggo/swaggo.io/c7bdcce3bc6103fd019cc6c885ff6edca0e21519/images/swagger-image.png)
225+
226+
## About the Project
227+
This project was inspired by [swagger](https://github.com/yvasiyarov/swagger) but simplified the usage of complexity and support a variety of [web framework]((#supported-web-framework)).
228+

‎declarative_comments_format/api_operation.md

Lines changed: 32 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,18 @@
11
# API Operation
22

3-
| annotation | description |
3+
| annotation | description |
44
|--------------------|-----------------------------------------------------------------------------------------------------------|
55
| description | A verbose explanation of the operation behavior. |
66
| id | A unique string used to identify the operation. Must be unique among all API operations. |
77
| tags | A list of tags to each API operation that separated by commas. |
88
| summary | A short summary of what the operation does. |
99
| accept | A list of MIME types the APIs can consume. Value MUST be as described under [Mime Types](#mime-types). |
1010
| produce | A list of MIME types the APIs can produce. Value MUST be as described under [Mime Types](#mime-types). |
11-
| param | Parameters that separated by spaces. `param name`,`param type`,`data type`,`is mandatory?`,`comment` |
12-
| success | Success response that separated by spaces. `return code`,`{param type}`,`data type`,`comment` |
13-
| failure | Failure response that separated by spaces. `return code`,`{param type}`,`data type`,`comment` |
14-
| router | Failure response that separated by spaces. `path`,`[httpMethod]` |
11+
| param | Parameters that separated by spaces. `param name`,`param type`,`data type`,`is mandatory?`,`comment` |
12+
| security | [Security](#security) to each API operation. |
13+
| success | Success response that separated by spaces. `return code`,`{param type}`,`data type`,`comment` |
14+
| failure | Failure response that separated by spaces. `return code`,`{param type}`,`data type`,`comment` |
15+
| router | Failure response that separated by spaces. `path`,`[httpMethod]` |
1516

1617
## Example
1718

@@ -37,6 +38,32 @@ json-api
3738
application/vnd.api+json
3839
```
3940

41+
## Security
42+
43+
General API info.
44+
45+
```go
46+
// @securityDefinitions.basic BasicAuth
47+
48+
// @securitydefinitions.oauth2.application OAuth2Application
49+
// @tokenUrl https://example.com/oauth/token
50+
// @scope.write Grants write access
51+
// @scope.admin Grants read and write access to administrative information
52+
```
53+
54+
Each API operation.
55+
56+
```go
57+
// @Security ApiKeyAuth
58+
```
59+
60+
Make it AND condition
61+
62+
```go
63+
// @Security ApiKeyAuth
64+
// @Security OAuth2Application[write, admin]
65+
```
66+
4067
## Param Type
4168

4269
- object (struct)

‎declarative_comments_format/general_api_info.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,17 @@
1414
| host | The host (name or ip) serving the API. |
1515
| BasePath | The base path on which the API is served. |
1616

17+
## Security
18+
19+
| annotation | description | parameters |
20+
|-----------------------------------------|------------------------------------------------------------------------------------------------|-----------------------------------|
21+
| securitydefinitions.basic | [Basic](https://swagger.io/docs/specification/2-0/authentication/basic-authentication/) auth. | |
22+
| securitydefinitions.apikey | [API key](https://swagger.io/docs/specification/2-0/authentication/api-keys/) auth. | in, name |
23+
| securitydefinitions.oauth2.application | [OAuth2 application](https://swagger.io/docs/specification/authentication/oauth2/) auth. | tokenUrl, scope |
24+
| securitydefinitions.oauth2.implicit | [OAuth2 implicit](https://swagger.io/docs/specification/authentication/oauth2/) auth. | authorizationUrl, scope |
25+
| securitydefinitions.oauth2.password | [OAuth2 password](https://swagger.io/docs/specification/authentication/oauth2/) auth. | tokenUrl, scope |
26+
| securitydefinitions.oauth2.accessCode | [OAuth2 access code](https://swagger.io/docs/specification/authentication/oauth2/) auth. | tokenUrl, authorizationUrl, scope |
27+
1728
## Example
1829

1930
[celler/main.go](https://github.com/swaggo/swag/blob/master/example/celler/main.go)

‎images/swagger-image.png

218 KB
Loading

0 commit comments

Comments
 (0)