canonical / maas.io

Site for maas.io

https://maas.io/

GNU Lesser General Public License v3.0

17 stars 42 forks source link

feat(docs): Replace static API docs with OpenAPI specification MAASENG-1120 #766

Closed ndv99 closed 1 year ago

ndv99 commented 1 year ago

Done

Added preprocessing of YAML to app.py to make it easier to parse
Wrote algorithms to parse YAML into readable HTML with endpoint information

QA

Pull this branch locally and run using dotrun
Navigate to /docs/api
Ensure that the styling is adequate and that information is displayed appropriately for each endpoint and method

Issue / Card

Fixes https://warthogs.atlassian.net/jira/software/c/projects/MAASENG/boards/302?modal=detail&selectedIssue=MAASENG-1120

Blockers

~~Blocked by: https://github.com/canonical/maas.io/pull/769~~

webteam-app commented 1 year ago

Demo starting at https://maas-io-766.demos.haus

petermakowski commented 1 year ago

@ndv99 Nice, almost there (the demo doesn't work, I get a server error).

Just noticed that the API link is an absolute link instead of a relative link (<a href="https://maas.io/docs/api">API documentation</a> instead of <a href="/docs/api">API documentation</a>). Would you mind updating that (as part of this PR or separately)?

ndv99 commented 1 year ago

@petermakowski

@ ndv99 Nice, almost there (the demo doesn't work, I get a server error).

Just noticed that the API link is an absolute link instead of a relative link (<a href="https://maas.io/docs/api">API documentation</a> instead of <a href="/docs/api">API documentation</a>). Would you mind updating that (as part of this PR or separately)?

I think fixing that link might be easier said than done, I'm struggling to find out where this link is actually generated. The only place I can find where it's directly referred to is in the site tour

codecov[bot] commented 1 year ago

Codecov Report

Merging #766 (e7bc4fc) into main (10311b2) will increase coverage by 1.94%. The diff coverage is 84.84%.

@@            Coverage Diff             @@
##             main     #766      +/-   ##
==========================================
+ Coverage   63.60%   65.55%   +1.94%     
==========================================
  Files           6        8       +2     
  Lines         327      360      +33     
==========================================
+ Hits          208      236      +28     
- Misses        119      124       +5

Flag	Coverage Δ
python	`65.55% <84.84%> (+1.94%)`	:arrow_up:

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
webapp/app.py	`70.00% <50.00%> (-1.88%)`	:arrow_down:
tests/test_openapi_parser.py	`90.00% <90.00%> (ø)`
webapp/openapi_parser.py	`94.11% <94.11%> (ø)`

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.