Generate swagger json

[sapk]

Use https://github.com/go-swagger/go-swagger with go generate to (auto-)build public/swagger.json

Related : #194 go-gitea/go-sdk#53

I will fill missing API descriptions. For the responses descriptions, tags must be add to sdk repo (so in a other PR).

You can test rendering at http://editor.swagger.io and copy-paste swagger.json.

Documented API :

• GET /version (getVersion)
• POST /markdown (renderMarkdown)
• POST /markdown/raw (renderMarkdownRaw)
• GET /users/search (userSearch)
• GET /users/:username (userGet)
• GET /user (userGetCurrent)
• GET /users/:username/tokens (userGetTokens)
• POST /users/:username/tokens (userCreateToken)
• GET /users/:username/repos (userListRepos)
• GET /user/repos (userCurrentListRepos)
• GET /user/keys userCurrentListKeys
• GET /users/:username/keys userListKeys
• GET /user/keys/:id userCurrentGetKey
• POST /user/keys userCurrentPostKey
• DELETE /user/keys/:id userCurrentDeleteKey
• GET /user/gpg_keys userCurrentListGPGKeys
• GET /users/:username/gpg_keys userListGPGKeys
• GET /user/gpg_keys/:id userCurrentGetGPGKey
• POST /user/gpg_keys userCurrentPostGPGKey
• DELETE /user/gpg_keys/:id userCurrentDeleteGPGKey
• GET /user/followers userCurrentListFollowers
• GET /users/:username/followers userListFollowers
• GET /user/following userCurrentListFollowing
• GET /users/:username/following userListFollowing
• GET /user/following/:username userCurrentCheckFollowing
• GET /users/:username/following/:target userCheckFollowing
• PUT /user/following/:username userCurrentPutFollow
• DELETE /user/following/:username userCurrentDeleteFollow
• GET /users/:username/starred userListStarred
• GET /user/starred userCurrentListStarred
• GET /user/starred/:username/:reponame userCurrentCheckStarring
• PUT /user/starred/:username/:reponame userCurrentPutStar
• DELETE /user/starred/:username/:reponame userCurrentDeleteStar
• GET /users/:username/subscriptions userListSubscriptions
• GET /user/subscriptions userCurrentListSubscriptions
• GET /repos/:username/:reponame/subscription userCurrentCheckSubscription
• PUT /repos/:username/:reponame/subscription userCurrentPutSubscription
• DELETE /repos/:username/:reponame/subscription userCurrentDeleteSubscription
• POST /org/:org/repos createOrgRepo
• ..

[lunny]

Maybe we need an API docs site? Or a link on docs.gitea.io?

[sapk]

Once fully implented we could use swagger ui for presentation. There is two choice possible :

• We use a remote one. This require to have CORS enable to be able to execute test request from ui. (example : http://petstore.swagger.io/)
• We use expose a swagger ui inside gitea and we have complete access to api and docs is accessible alongside gitea.

As global documentation we could start a docker containing swagger ui (allready avalaibe) for try.gitea.io : https://github.com/swagger-api/swagger-ui

[sapk]

I think that I will simply copy https://github.com/swagger-api/swagger-ui/tree/master/dist into public/assets. This will provide swagger-ui on all instance.

[lunny]

@sapk so add new make subcommand is enough?

[sapk]

@lunny For generating swagger.json, I added a go generate here :
https://github.com/go-gitea/gitea/pull/1402/files#diff-2620fdbeeb83ce43692534e6c2c39452R5

So make generate will update it and place it under public folder.

For swagger-ui, I am thinking of adding a other step to make assets

[sapk]

In parallel, I will PR to fix little things like go-gitea/go-sdk#50 (it will need a PR in gitea also) to put all data structure under go-sdk and add missing api request. A other PR to go-gitea/go-sdk will be added to add swagger comment to api response and params.

This PR is a long running one to complete ^^. It will maybe need a second pass to adjust comments but the base will be there.

[lunny]

Or maybe we can add a link on the bottom or top on Gitea named API to the API docs home page.

[bkcsoft]

maybe use "s;https://...;...;g" instead for readability?

[sapk]

I am not a big expert in sed. ^^

[bkcsoft]

Just download a tar.gz release instead. We shouldn't depend on latest master being functional

[sapk]

I use git tag now to fix the version. (less things to change ^^)

[bkcsoft]

Maybe update the doc links while you're at it :)

[bkcsoft]

Or remove them since they now become redundant 😅

[bkcsoft]

This needs to be fixed before merge :)

[sapk]

Yes this temporary and will be added in a PR in sdk. All the input and output format (used by api) are in sdk and I have already done one PR to move a struct in gitea to sdk.

[bkcsoft]

Actually, would it make sense to have this in go-gitea/sdk instead?

[lunny]

Is this still WIP?

[sapk]

@lunny yes because it is missing some api url and it need a PR in sdk for all format response and request. But you can review tooling around it like Makefile and the only changes that will append next are swagger comment so It will be ready to merge when complete.

[lunny]

@sapk maybe move this to v1.3?

[sapk]

@lunny There is two possibility :

• Push it in v1.2, everything is working it just need to doc (add comment) to the not yet documented API in other(s) PR.
• Wait v1.3 to have complete documentation.

[bkcsoft]

@lunny @sapk For API-docs I'm actually fine with having partial docs for a while. Better than to have no docs at all 😅

[bkcsoft]

This will have my LG-TM once the gogs docs links are gone 🙂

[jonasfranz]

The swagger file is not complete. Some parts of the API are missing like the issue management.

[sapk]

@JonasFranzDEV That what I say ^^
@bkcsoft ok I will clean this up for fully documented in swagger

[sapk]

I rebase/squash all changes into a fully working version. I vendor go-gitea/go-sdk#53 in the wait of it validation so that this PR is working for validation also. I will revert it back as soon that go-gitea/go-sdk/pull/53 is merged.

For testing, just build gitea like always, start it, and go to http://localhost:3000/swagger

Fix/Hack that I have implemented : (This is if someone has a better/cleaner idea)

• Swagger-ui doesn't support recursive deps like GPGKey that contain sub-GPGKey that contain .... -> I use a sedin go generate to set sub-GPGKey as object.

Improvements to be done in other PR :

• Add all missing API
• Improve documentation of parameters and responses. (For example : add a regex for armored key params)
• Add params for in url/path params. As of now they are displayed but we need struct to link them to params in code and be able to set them in swagger-ui.

Over all, this PR should not have an big impact on code functionality as it is mostly comments.

[lunny]

@sapk I like first chosen. So is it ready to review and merge?

[sapk]

@lunny Yes, the only thing that bother me is the little fix/hack for recursive structure not supported by swagger-ui but we need it. (describe in my previous comment)

[KangoV]

Which version are you using? We've just switched to using swagger-ui v3.0.7. Has a much nicer look. This is getting ready for OpenAPI v3.0 later in the year: http://swagger.io/new-swagger-ui-and-swagger-editor/.
It's also much easier to integrate.

[sapk]

@KangoV I have added swagger-ui v3.0.7 (get via makefile). I used go-swagger to generate the JSON from code comments.

[lunny]

Is this ready for review?

[sapk]

@lunny yes like I said two days ago ^^
and since go-gitea/go-sdk#53 is merged so nothing else to do.

[lunny]

LGTM

[bkcsoft]

LGTM

[bkcsoft]

make LG-TM work