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]

Codecov Report

Attention: Patch coverage is 84.61538% with 2 lines in your changes missing coverage. Please review.

Project coverage is 74.82%. Comparing base (4658bec) to head (0a59f53).

Files with missing lines	Patch %	Lines
api/router.go	83.33%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1359      +/-   ##
==========================================
- Coverage   74.83%   74.82%   -0.01%     
==========================================
  Files         151      151              
  Lines       17119    17129      +10     
==========================================
+ Hits        12811    12817       +6     
- Misses       3286     3289       +3     
- Partials     1022     1023       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.