QA (public) » openQA Project (public)

Could do some research about this, maybe it is not bad if someone who haven't used the api a lot comes up with some ideas.

Mojolicious::Plugin::Swagger2 is now deprecated, worth maybe considering [1].

Also if Swagger seems nice, i personally like more POD, the inner benefit is having comments straight into the code as well while you can export them in different formats.

I used dzil/minil to manage Perl project, and they comes with nice plugins to convert automatically POD into documentation, with the need to just specify the prefered way of exporting in your project's dist.ini.

E.g. in one of my old projects i quickly come up with this [2] that converts all the POD detected from the project into a markdown structure, suitable to generate automatically a wiki within a GitHub project; the benefit to stick with POD imho is we could convert it also in other formats pretty easily.

[1] https://metacpan.org/pod/Mojolicious::Plugin::OpenAPI
[2] https://gist.github.com/mudler/807f8f71a88cace91a8fbbbd5faf01f3

thanks for your hints. But do you have more specific pointers how to actually proceed to have better API documentation within openQA?

what i'd do is commenting with POD and create a script under the script/ folder that takes cares of converting POD to the format we decide to stick to. Then we can call the script during the release process, in the Makefile, or also in git post-hooks. If that sounds good i could proceed to create a small PoC

yes, sounds good to me. Please go ahead.

E.g. https://github.com/mudler/openQA/wiki/OpenQA::Client

Generated from: https://github.com/mudler/openQA/blob/docs-md/script/generate-wiki-from-pod

Since we don't have as for now any POD comment in OpenQA.pm there was generated no "Home page" for the wiki, and just couple of few pages for the same reason - but if we don't like to pollute the github wiki, with the same approach we could also export the generated documentation in a separate git repository just containing MD files.

Well actually the point is about the web API of openQA itself, e.g. take a look on the whole route table as seen on https://openqa.opensuse.org/all_the_routes

indeed it could be used also to document the web API as well, using POD to comment the API and providing at the same time human-readable documentation in the code

Mojolicious::Plugin::OpenAPI documentation:

This plugin reads an OpenAPI specification and generate routes and input/output rules from it.

We already have the routes and only need the documentation. So we needed a tool to generate the documentation (maybe as OpenAPI specification) from existing routes which is quite the opposite of what the plugin Mojolicious::Plugin::OpenAPI provides.

Not sure whether POD fits here. Of course it would be possible to add POD documentation to eg. sub cancel in Job.pm and parse it. However, in this context the specification of the route itself (POST /jobs/cancel, operator-only) is not available because it is defined in WebAPI.pm.

Mojolicous already has meta-data about each route - its name, the access permissions and available methods. The name and available methods can already be displayed for each route: https://openqa.suse.de/api_documentation.

So in my opinion it would make sense to extend the already existing approach by adding further meta-data to the routes, eg. a description and expected parameter. Of course the current error page would need to be improved to be more readable. Maybe some of the less common routes should be hidden or moved to the bottom.

To do this, we would need to extend the route objects provided by Mojolicous.

@kraih Would this approach make sense? Maybe you have a better idea or already have done this in a Mojo app?

@kraih Would this approach make sense? Maybe you have a better idea or already have done this in a Mojo app?

Using route introspection seems like a bit of a dead end to me, there is no meta data available for what HTTP
headers and JSON documents your API endpoints accept and generate. Personally, i've always written API
docs manually so far. But if your API fits into the OpenAPI mold, that could be a reasonable choice.

Using route introspection seems like a bit of a dead end to me...

I mean, theoretically you can definitely do it. But the meta data would only serve documentation
purposes, and at that point how is it any better than maintaining it as POD in the first place? I can
only see downsides i'm afraid.

https://github.com/os-autoinst/openQA/pull/1439

Opened a PR for a description part on the not_found page where all the api routes are listed. Since we need a description anyway (no matter which way the ticket will go) I would suggest to start writing descriptions in the next step.

Proposal for API documentation extracted from controller modules POD: https://github.com/os-autoinst/openQA/pull/1559