Skip to content

Commit ce26e50

Browse files
tobiasehlerttobiasehlert
authored
add swagger generation of documentation (#67)
1 parent 9077145 commit ce26e50

File tree

4 files changed

+252
-2
lines changed

4 files changed

+252
-2
lines changed

‎.github/workflows/documentation.yml‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
name: documentation
2+
3+
on:
4+
push:
5+
tags:
6+
- "v*"
7+
8+
jobs:
9+
documentation:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- name: Checkout
13+
uses: actions/checkout@v2
14+
15+
- name: Set up Go
16+
uses: actions/setup-go@v2
17+
with:
18+
go-version: 1.17
19+
20+
- name: Install swag by swaggo
21+
run: |
22+
go install github.com/swaggo/swag/cmd/swag@latest
23+
24+
- name: Run swag to initiate docs
25+
run: |
26+
swag init --dir=src/
27+
28+
- name: Manipulate swagger.json with Release info
29+
run: |
30+
# set version of swagger.json to release name
31+
cat docs/swagger.json | jq '.info.version = "${{ github.event.release.tag_name }}"' > docs/swagger.json
32+
33+
- name: Upload swagger.json to release page
34+
uses: svenstaro/upload-release-action@v2
35+
with:
36+
repo_token: ${{ secrets.GITHUB_TOKEN }}
37+
file: docs/swagger.json
38+
tag: ${{ github.ref }}
39+
40+
- name: Trigger workflow in tibiadata-api-docs repo
41+
run: |
42+
curl -X POST \
43+
-H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
44+
-H "Accept: application/vnd.github.v3+json" \
45+
-d '{"ref":"main"}' \
46+
https://api.github.com/repos/TibiaData/tibiadata-api-docs/actions/workflows/update.yml/dispatches

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -87,9 +87,9 @@ We do so at least by using [Kong](https://github.com/Kong/kong) API Gateway, whi
8787

8888
## API documentation
8989

90-
Current status of v3 is in beta and information like documentation can be found on [tibiadata.com](https://tibiadata.com/doc-api-v3/v3-beta/).
90+
The hosted API documentation for our [api.tibiadata.com](https://api.tibiadata.com) service can be viewd at [docs.tibiadata.com](https://docs.tibiadata.com).
9191

92-
There will be autogenerated code-documentation available later on.
92+
There is a swagger-generated documentation available for download on the [GitHub Release](https://github.com/TibiaData/tibiadata-api-go/releases) of the version you are looking for.
9393

9494
### Available endpoints
9595

‎src/main.go‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,23 @@ var (
2020
TibiadataBuildEdition = "open-source" //
2121
)
2222

23+
// @title TibiaData API
24+
// @version edge
25+
// @description This is the API documentation for the TibiaData API.
26+
// @description The documentation contains version 3 and above.
27+
// @termsOfService https://tibiadata.com/terms/
28+
29+
// @contact.name TibiaData
30+
// @contact.url https://www.tibiadata.com/contact/
31+
// @contact.email tobias@tibiadata.com
32+
33+
// @license.name MIT
34+
// @license.url https://github.com/TibiaData/tibiadata-api-go/blob/main/LICENSE
35+
36+
// @schemes http
37+
// @host localhost:8080
38+
// @BasePath /
39+
2340
func main() {
2441
// logging start of TibiaData
2542
log.Printf("[info] TibiaData API starting..")
@@ -75,4 +92,8 @@ func TibiaDataInitializer() {
7592
// initializing houses mappings
7693
TibiaDataHousesMappingInitiator()
7794

95+
// run some functions that are empty but required for documentation to be done
96+
_ = tibiaNewslistArchiveV3()
97+
_ = tibiaNewslistArchiveDaysV3()
98+
_ = tibiaNewslistLatestV3()
7899
}

‎src/webserver.go‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,15 @@ func runWebServer() {
134134
_ = router.Run() // listen and serve on 0.0.0.0:8080 (for windows "localhost:8080")
135135
}
136136

137+
// Character godoc
138+
// @Summary Show one character
139+
// @Description Show all information about one character available
140+
// @Tags characters
141+
// @Accept json
142+
// @Produce json
143+
// @Param character path string true "The character name"
144+
// @Success 200 {object} CharacterResponse
145+
// @Router /v3/characters/character/{character} [get]
137146
func tibiaCharactersCharacterV3(c *gin.Context) {
138147
// getting params from URL
139148
character := c.Param("character")
@@ -152,6 +161,14 @@ func tibiaCharactersCharacterV3(c *gin.Context) {
152161
"TibiaCharactersCharacterV3")
153162
}
154163

164+
// Creatures godoc
165+
// @Summary List of creatures
166+
// @Description Show all creatures listed
167+
// @Tags creatures
168+
// @Accept json
169+
// @Produce json
170+
// @Success 200 {object} CreaturesOverviewResponse
171+
// @Router /v3/creatures [get]
155172
func tibiaCreaturesOverviewV3(c *gin.Context) {
156173
tibiadataRequest := TibiadataRequestStruct{
157174
Method: resty.MethodGet,
@@ -167,6 +184,15 @@ func tibiaCreaturesOverviewV3(c *gin.Context) {
167184
"TibiaCreaturesOverviewV3")
168185
}
169186

187+
// Creature godoc
188+
// @Summary Show one creature
189+
// @Description Show all information about one creature
190+
// @Tags creatures
191+
// @Accept json
192+
// @Produce json
193+
// @Param race path string true "The race of creature"
194+
// @Success 200 {object} CreatureResponse
195+
// @Router /v3/creatures/creature/{race} [get]
170196
func tibiaCreaturesCreatureV3(c *gin.Context) {
171197
// getting params from URL
172198
race := c.Param("race")
@@ -185,6 +211,14 @@ func tibiaCreaturesCreatureV3(c *gin.Context) {
185211
"TibiaCreaturesCreatureV3")
186212
}
187213

214+
// Fansites godoc
215+
// @Summary Promoted and supported fansites
216+
// @Description List of all promoted and supported fansites
217+
// @Tags fansites
218+
// @Accept json
219+
// @Produce json
220+
// @Success 200 {object} FansitesResponse
221+
// @Router /v3/fansites [get]
188222
func tibiaFansitesV3(c *gin.Context) {
189223
tibiadataRequest := TibiadataRequestStruct{
190224
Method: resty.MethodGet,
@@ -200,6 +234,15 @@ func tibiaFansitesV3(c *gin.Context) {
200234
"TibiaFansitesV3")
201235
}
202236

237+
// Guild godoc
238+
// @Summary Show one guild
239+
// @Description Show all information about one guild
240+
// @Tags guilds
241+
// @Accept json
242+
// @Produce json
243+
// @Param guild path string true "The name of guild"
244+
// @Success 200 {object} GuildResponse
245+
// @Router /v3/guilds/guild/{guild} [get]
203246
func tibiaGuildsGuildV3(c *gin.Context) {
204247
// getting params from URL
205248
guild := c.Param("guild")
@@ -218,6 +261,15 @@ func tibiaGuildsGuildV3(c *gin.Context) {
218261
"TibiaGuildsGuildV3")
219262
}
220263

264+
// Guilds godoc
265+
// @Summary List all guilds from a world
266+
// @Description Show all guilds on a certain world
267+
// @Tags guilds
268+
// @Accept json
269+
// @Produce json
270+
// @Param world path string true "The world"
271+
// @Success 200 {object} GuildsOverviewResponse
272+
// @Router /v3/guilds/world/{world} [get]
221273
func tibiaGuildsOverviewV3(c *gin.Context) {
222274
// getting params from URL
223275
world := c.Param("world")
@@ -239,6 +291,17 @@ func tibiaGuildsOverviewV3(c *gin.Context) {
239291
"TibiaGuildsOverviewV3")
240292
}
241293

294+
// Highscores godoc
295+
// @Summary Highscores of tibia
296+
// @Description Show all highscores of tibia
297+
// @Tags highscores
298+
// @Accept json
299+
// @Produce json
300+
// @Param world path string true "The world (default: all)"
301+
// @Param category path string true "The category (default: experience)"
302+
// @Param vocation path string true "The vocation (default: all)"
303+
// @Success 200 {object} HighscoresResponse
304+
// @Router /v3/highscores/world/{world}/{category}/{vocation} [get]
242305
func tibiaHighscoresV3(c *gin.Context) {
243306
// getting params from URL
244307
world := c.Param("world")
@@ -273,6 +336,16 @@ func tibiaHighscoresV3(c *gin.Context) {
273336
"TibiaHighscoresV3")
274337
}
275338

339+
// House godoc
340+
// @Summary House view
341+
// @Description Show all information about one house
342+
// @Tags houses
343+
// @Accept json
344+
// @Produce json
345+
// @Param world path string true "The world to show"
346+
// @Param houseid path int true "The ID of the house"
347+
// @Success 200 {object} HouseResponse
348+
// @Router /v3/houses/world/{world}/house/{houseid} [get]
276349
func tibiaHousesHouseV3(c *gin.Context) {
277350
// getting params from URL
278351
world := c.Param("world")
@@ -295,6 +368,16 @@ func tibiaHousesHouseV3(c *gin.Context) {
295368
"TibiaHousesHouseV3")
296369
}
297370

371+
// Houses godoc
372+
// @Summary List of houses
373+
// @Description Show all houses filtered on world and town
374+
// @Tags houses
375+
// @Accept json
376+
// @Produce json
377+
// @Param world path string true "The world to show"
378+
// @Param town path string true "The town to show"
379+
// @Success 200 {object} HousesOverviewResponse
380+
// @Router /v3/houses/world/{world}/town/{town} [get]
298381
//TODO: This API needs to be refactored somehow to use tibiaDataRequestHandler
299382
func tibiaHousesOverviewV3(c *gin.Context) {
300383
// getting params from URL
@@ -311,6 +394,15 @@ func tibiaHousesOverviewV3(c *gin.Context) {
311394
TibiaDataAPIHandleResponse(c, http.StatusOK, "TibiaHousesOverviewV3", jsonData)
312395
}
313396

397+
// Killstatistics godoc
398+
// @Summary The killstatistics
399+
// @Description Show all killstatistics filtered on world
400+
// @Tags killstatistics
401+
// @Accept json
402+
// @Produce json
403+
// @Param world path string true "The world to show"
404+
// @Success 200 {object} KillStatisticsResponse
405+
// @Router /v3/killstatistics/world/{world} [get]
314406
func tibiaKillstatisticsV3(c *gin.Context) {
315407
// getting params from URL
316408
world := c.Param("world")
@@ -332,6 +424,54 @@ func tibiaKillstatisticsV3(c *gin.Context) {
332424
"TibiaKillstatisticsV3")
333425
}
334426

427+
// News archive godoc
428+
// @Summary Show news archive (90 days)
429+
// @Description Show news archive with a filtering on 90 days
430+
// @Tags news
431+
// @Accept json
432+
// @Produce json
433+
// @Success 200 {object} NewsListResponse
434+
// @Router /v3/news/archive [get]
435+
func tibiaNewslistArchiveV3() bool {
436+
// Not used function.. but required for documentation purpose
437+
return false
438+
}
439+
440+
// News archive (with day filter) godoc
441+
// @Summary Show news archive (with days filter)
442+
// @Description Show news archive with a filtering option on days
443+
// @Tags news
444+
// @Accept json
445+
// @Produce json
446+
// @Param days path int true "The number of days to show"
447+
// @Success 200 {object} NewsListResponse
448+
// @Router /v3/news/archive/{days} [get]
449+
func tibiaNewslistArchiveDaysV3() bool {
450+
// Not used function.. but required for documentation purpose
451+
return false
452+
}
453+
454+
// Latest news godoc
455+
// @Summary Show newslist (90 days)
456+
// @Description Show newslist with filtering on articles and news of last 90 days
457+
// @Tags news
458+
// @Accept json
459+
// @Produce json
460+
// @Success 200 {object} NewsListResponse
461+
// @Router /v3/news/latest [get]
462+
func tibiaNewslistLatestV3() bool {
463+
// Not used function.. but required for documentation purpose
464+
return false
465+
}
466+
467+
// News ticker godoc
468+
// @Summary Show news tickers (90 days)
469+
// @Description Show news of type news tickers of last 90 days
470+
// @Tags news
471+
// @Accept json
472+
// @Produce json
473+
// @Success 200 {object} NewsListResponse
474+
// @Router /v3/news/newsticker [get]
335475
func tibiaNewslistV3(c *gin.Context) {
336476
// getting params from URL
337477
days := TibiadataStringToIntegerV3(c.Param("days"))
@@ -383,6 +523,15 @@ func tibiaNewslistV3(c *gin.Context) {
383523
"TibiaNewslistV3")
384524
}
385525

526+
// News entry godoc
527+
// @Summary Show one news entry
528+
// @Description Show one news entry
529+
// @Tags news
530+
// @Accept json
531+
// @Produce json
532+
// @Param news_id path int true "The ID of news entry"
533+
// @Success 200 {object} NewsResponse
534+
// @Router /v3/news/id/{news_id} [get]
386535
func tibiaNewsV3(c *gin.Context) {
387536
// getting params from URL
388537
NewsID := TibiadataStringToIntegerV3(c.Param("news_id"))
@@ -407,6 +556,14 @@ func tibiaNewsV3(c *gin.Context) {
407556
"TibiaNewsV3")
408557
}
409558

559+
// Spells godoc
560+
// @Summary List all spells
561+
// @Description Show all spells
562+
// @Tags spells
563+
// @Accept json
564+
// @Produce json
565+
// @Success 200 {object} SpellsOverviewResponse
566+
// @Router /v3/spells [get]
410567
func tibiaSpellsOverviewV3(c *gin.Context) {
411568
// getting params from URL
412569
vocation := c.Param("vocation")
@@ -439,6 +596,15 @@ func tibiaSpellsOverviewV3(c *gin.Context) {
439596
"TibiaSpellsOverviewV3")
440597
}
441598

599+
// Spell godoc
600+
// @Summary Show one spell
601+
// @Description Show all information about one spell
602+
// @Tags spells
603+
// @Accept json
604+
// @Produce json
605+
// @Param spell path string true "The name of spell"
606+
// @Success 200 {object} SpellInformationResponse
607+
// @Router /v3/spells/spell/{spell} [get]
442608
func tibiaSpellsSpellV3(c *gin.Context) {
443609
// getting params from URL
444610
spell := c.Param("spell")
@@ -457,6 +623,14 @@ func tibiaSpellsSpellV3(c *gin.Context) {
457623
"TibiaSpellsSpellV3")
458624
}
459625

626+
// Worlds godoc
627+
// @Summary List of all worlds
628+
// @Description Show all worlds of Tibia
629+
// @Tags worlds
630+
// @Accept json
631+
// @Produce json
632+
// @Success 200 {object} WorldsOverviewResponse
633+
// @Router /v3/worlds [get]
460634
func tibiaWorldsOverviewV3(c *gin.Context) {
461635
tibiadataRequest := TibiadataRequestStruct{
462636
Method: resty.MethodGet,
@@ -472,6 +646,15 @@ func tibiaWorldsOverviewV3(c *gin.Context) {
472646
"TibiaWorldsOverviewV3")
473647
}
474648

649+
// World godoc
650+
// @Summary Show one world
651+
// @Description Show all information about one world
652+
// @Tags worlds
653+
// @Accept json
654+
// @Produce json
655+
// @Param world path string true "The name of world"
656+
// @Success 200 {object} WorldResponse
657+
// @Router /v3/worlds/world/{world} [get]
475658
func tibiaWorldsWorldV3(c *gin.Context) {
476659
// getting params from URL
477660
world := c.Param("world")

0 commit comments

Comments
 (0)