Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve/documentation #1359

Open
wants to merge 6 commits into
base: master
Choose a base branch
from
Open

Improve/documentation #1359

wants to merge 6 commits into from

Conversation

neolynx
Copy link
Member

@neolynx neolynx commented Oct 4, 2024

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

image

image

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?)

Copy link

codecov bot commented Oct 4, 2024

Codecov Report

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

Project coverage is 74.88%. Comparing base (767bc6b) to head (cafd7d0).

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.89%   74.88%   -0.01%     
==========================================
  Files         151      151              
  Lines       17161    17171      +10     
==========================================
+ Hits        12852    12858       +6     
- Misses       3284     3287       +3     
- Partials     1025     1026       +1     

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

@neolynx neolynx self-assigned this Oct 4, 2024
@neolynx neolynx added the help wanted ! Please help getting this PR merged :-) label Oct 4, 2024
@neolynx neolynx requested a review from a team October 4, 2024 14:41
@neolynx neolynx added the WIP label Oct 5, 2024
@neolynx neolynx force-pushed the improve/documentation branch 5 times, most recently from f7903cb to af56e15 Compare October 9, 2024 18:13
- use markdown files in swagger
- automate version, use swager.conf template
- embed swagger ui index.html as docs.html
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
help wanted ! Please help getting this PR merged :-) WIP
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants