action #16282

[tools][sprint 201711.2] documentation: Better API documentation

Added by okurz about 3 years ago. Updated almost 2 years ago.

Status:ResolvedStart date:27/01/2017
Priority:NormalDue date:
Assignee:acarvajal% Done:

0%

Category:Feature requests
Target version:Done
Difficulty:
Duration:

Description

User story

As an openQA API user I want documentation of available API commands in easier to read format so that I am motivated to use the API more often

acceptance criteria

  • AC1: the API documentation provides grouping based on use cases
  • AC2: documentation provides something human readable
  • AC3: documentation is automatically updated from source code

tasks

further details

Currently we have all available API routes listed on all unknown routes, e.g. https://openqa.opensuse.org/all_the_routes but they are missing some human description and are also not grouped in a sensible way by use, only by definition.

Other interesting references:
* http://petstore.swagger.io/#!/pet/addPet
* http://raml.org/
* http://apidocjs.com

History

#1 Updated by okurz about 3 years ago

  • Description updated (diff)

#2 Updated by okurz almost 3 years ago

  • Description updated (diff)

added http://apidocjs.com, maybe nice idea as well.

#3 Updated by okurz almost 3 years ago

  • Target version changed from Milestone 6 to Milestone 7

no capacity

#4 Updated by krauselukas almost 3 years ago

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.

#5 Updated by EDiGiacinto almost 3 years ago

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

#6 Updated by okurz almost 3 years ago

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

#7 Updated by EDiGiacinto almost 3 years ago

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

#8 Updated by okurz almost 3 years ago

yes, sounds good to me. Please go ahead.

#9 Updated by EDiGiacinto almost 3 years ago

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.

#10 Updated by okurz almost 3 years ago

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

#11 Updated by EDiGiacinto almost 3 years ago

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

#12 Updated by maritawerner over 2 years ago

  • Target version changed from Milestone 7 to Milestone 9

Milestone 7 is done. I will move that to milestone 9. Is that related to the Dashboard? Or for the Tools group?

#13 Updated by mkittler over 2 years ago

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?

#14 Updated by kraih over 2 years ago

@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.

#15 Updated by kraih over 2 years ago

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.

#16 Updated by krauselukas over 2 years ago

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.

#17 Updated by okurz over 2 years ago

  • Target version changed from Milestone 9 to future

M9 is over, I guess there is no current milestone where this will be expected.

#18 Updated by EDiGiacinto over 2 years ago

  • Subject changed from documentation: Better API documentation to [sprint 201710.2] documentation: Better API documentation
  • Assignee set to acarvajal

acarvajal is looking into it

#19 Updated by szarate over 2 years ago

  • Subject changed from [sprint 201710.2] documentation: Better API documentation to [sprint 201710.2][sprint 201711.1] documentation: Better API documentation

#20 Updated by szarate over 2 years ago

  • Subject changed from [sprint 201710.2][sprint 201711.1] documentation: Better API documentation to [tools][sprint 201711.2] documentation: Better API documentation

#21 Updated by acarvajal about 2 years ago

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

#22 Updated by acarvajal about 2 years ago

  • Target version changed from future to Current Sprint

#23 Updated by acarvajal about 2 years ago

  • Status changed from New to In Progress

#24 Updated by acarvajal about 2 years ago

  • Status changed from In Progress to Resolved

Pull request 1559 was merged. Updating this to Resolved.

#25 Updated by szarate almost 2 years ago

  • Target version changed from Current Sprint to Done

Also available in: Atom PDF