Improve/documentation

[neolynx]

Description of the Change

Document all APIs with swagger

In order to replace / automate the API documentation on https://www.aptly.info/doc/api document API calls with swagger.

About 40 APIs currently only have stubs and need to be documented:

git grep "@Summary TODO"

Run swagger

make docker-dev-server

See Swagger doc: http://localhost:3142/docs

Note: as the dev server has live reload, changes to the code will be recompiled, then the page can be reloaded.

Examples

• GET Request: https://github.com/aptly-dev/aptly/blob/improve/documentation/api/mirror.go#L220 (returning object)

• GET Request: https://github.com/aptly-dev/aptly/blob/improve/documentation/api/mirror.go#L34 (returning a list)

• POST Request: https://github.com/aptly-dev/aptly/blob/improve/documentation/api/mirror.go#L54 (with json body params)

• Object: https://github.com/aptly-dev/aptly/blob/improve/documentation/deb/remote.go#L36 (used in response)

• Header:https://github.com/aptly-dev/aptly/blob/improve/documentation/api/api.go#L47 (long description with bullet list)

Document aptly.conf

Found that aptly uses github.com/DisposaBoy/JsonConfigReader already, tunrs our it supports comments in json, so we can have a inline documented config file.

Checklist

• [ ] man page updated (if applicable)
• [ ] swagger documentation updated
• [ ] pipeline to publish CI or Release doc somewhere (gh-pages / aptly.info?)

[codecov[bot]]

Codecov Report

Attention: Patch coverage is 77.77778% with 10 lines in your changes missing coverage. Please review.

Project coverage is 75.02%. Comparing base (f9ae9b3) to head (e319f3c). Report is 39 commits behind head on master.

Files with missing lines	Patch %	Lines
utils/config.go	70.00%	2 Missing and 1 partial :warning:
api/repos.go	50.00%	2 Missing :warning:
api/router.go	83.33%	1 Missing and 1 partial :warning:
context/context.go	75.00%	1 Missing and 1 partial :warning:
main.go	0.00%	1 Missing :warning:

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1359      +/-   ##
==========================================
- Coverage   75.12%   75.02%   -0.10%     
==========================================
  Files         157      157              
  Lines       18172    18146      -26     
==========================================
- Hits        13651    13614      -37     
- Misses       3404     3409       +5     
- Partials     1117     1123       +6     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[iofq]

Working on filling in TODO stubs, starting with api/task

[neolynx]

Working on filling in TODO stubs, starting with api/task

thank you so much in advance !

[neolynx]

I pushed a fix for lint, please git pull --rebase :-)

[iofq]

Believe I took care of all the API stubs