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

All modified and coverable lines are covered by tests ✅

Project coverage is 74.80%. Comparing base (d6a156b) to head (5156aa0).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1359   +/-   ##
=======================================
  Coverage   74.80%   74.80%           
=======================================
  Files         151      151           
  Lines       17121    17121           
=======================================
  Hits        12808    12808           
  Misses       3290     3290           
  Partials     1023     1023           

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