Mojolicious::Plugin::OpenAPI PoC

https://progress.opensuse.org/issues/186675

Author: perlpunk

lib/OpenQA/WebAPI.pm

@@ -24,6 +24,11 @@ sub startup ($self) {
     # Some plugins are shared between openQA micro services
     push @{$self->plugins->namespaces}, 'OpenQA::Shared::Plugin';
     $self->plugin('SharedHelpers');
+    $self->plugin(
+        OpenAPI => {
+          url => $self->home->rel_file('public/openapi.yaml'),
+        },
+    );
 
     # Provide help to users early to prevent failing later on misconfigurations
     # note: Loading plugins for the current configuration so the help of commands provided by plugins is
@@ -52,7 +57,7 @@ sub startup ($self) {
     OpenQA::Schema->singleton;
 
     # Some controllers are shared between openQA micro services
-    my $r = $self->routes->namespaces(['OpenQA::Shared::Controller', 'OpenQA::WebAPI::Controller', 'OpenQA::WebAPI']);
+    my $r = $self->routes->namespaces([qw(OpenQA::Shared::Controller OpenQA::WebAPI::Controller OpenQA::WebAPI OpenQA::WebAPI::Controller::API::V1)]);
 
     # register basic routes
     my $logged_in = $r->under('/')->to('session#ensure_user');
@@ -325,12 +330,12 @@ sub startup ($self) {
 
     my $job_r = $api_ro->any('/jobs/<jobid:num>');
     push @api_routes, $job_r;
-    $api_public_r->any('/jobs/<jobid:num>')->name('apiv1_job')->to('job#show');
+#    $api_public_r->any('/jobs/<jobid:num>')->name('apiv1_job')->to('job#show');
     $api_public_r->get('/experimental/jobs/<jobid:num>/status')->name('apiv1_get_status')->to('job#get_status');
-    $api_public_r->any('/jobs/<jobid:num>/details')->name('apiv1_job')->to('job#show', details => 1);
+#    $api_public_r->any('/jobs/<jobid:num>/details')->name('apiv1_job')->to('job#show', details => 1);
     $job_r->put('/')->name('apiv1_put_job')->to('job#update');
     $job_r->delete('/')->name('apiv1_delete_job')->to('job#destroy');
-    $job_r->post('/prio')->name('apiv1_job_prio')->to('job#prio');
+#    $job_r->post('/prio')->name('apiv1_job_prio')->to('job#prio');
     $job_r->post('/set_done')->name('apiv1_set_done')->to('job#done');
     $job_r->post('/status')->name('apiv1_update_status')->to('job#update_status');
     $job_r->post('/artefact')->name('apiv1_create_artefact')->to('job#create_artefact');

lib/OpenQA/WebAPI/Controller/API/V1/Job.pm

@@ -455,6 +455,7 @@ Pass follow=1 as query param to follow job clones and report most recent result
 =cut
 
 sub show ($self) {
+    $self->openapi->valid_input or return;
     my $job_id = int($self->stash('jobid'));
     my $details = $self->stash('details') || 0;
     my $check_assets = !!$self->param('check_assets');
@@ -466,6 +467,11 @@ sub show ($self) {
     $self->render(json => {job => $job});
 }
 
+sub show_details ($self) {
+    $self->stash(details => 1);
+    show($self);
+}
+
 =over 4
 
 =item destroy()
@@ -494,10 +500,9 @@ Sets priority for a given job.
 =cut
 
 sub prio ($self) {
+    $self->openapi->valid_input or return;
     return unless my $job = $self->find_job_or_render_not_found($self->stash('jobid'));
-    my $v = $self->validation;
-    my $prio = $v->required('prio')->num->param;
-    return $self->reply->validation_error({format => 'json'}) if $v->has_error;
+    my $prio = $self->param('prio');
 
     # Referencing the scalar will result in true or false (see http://mojolicio.us/perldoc/Mojo/JSON)
     $self->render(json => {result => \$job->set_prio($prio)});

public/openapi.yaml

@@ -0,0 +1,65 @@
+openapi: 3.1.1
+info:
+  title: OpenQA API
+  version: v1
+servers:
+  - url: /api/v1
+
+paths:
+
+  /jobs/{jobid}:
+    parameters:
+    - &jobid
+      name: jobid
+      in: path
+      required: true
+      schema:
+        type: integer
+    get:
+      description: >
+        Shows details for a specific job, such as the assets associated, assigned
+        worker id, children and parents, job id, group id, name, parent group id
+        and name, priority, result, settings, state and times of startup and
+        finish of the job.
+      tags: [ job ]
+      x-mojo-name: apiv1_job
+      x-mojo-to: job#show
+      parameters:
+      - name: follow
+        description: >
+          Enable following job clones and report most recent result for a given
+          job id
+        in: query
+        schema:
+          type: integer
+          enum: [0, 1]
+      responses: {}
+
+  /jobs/{jobid}/details:
+    parameters:
+    - *jobid
+    get:
+      description: Show job with details (logs, testresults)
+      tags: [ job ]
+      x-mojo-name: apiv1_job_details
+      x-mojo-to: job#show_details
+      responses: {}
+
+  /jobs/{jobid}/prio:
+    parameters:
+    - *jobid
+    post:
+      description: Sets priority for a given job.
+      tags: [ job ]
+      x-mojo-name: apiv1_job_prio
+      x-mojo-to: job#prio
+      requestBody:
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              required: [ prio ]
+              properties:
+                prio:
+                  type: integer
+                  pattern: ^$
+      responses: {}

t/43-openapi.t

@@ -0,0 +1,29 @@
+# Copyright SUSE LLC
+# SPDX-License-Identifier: GPL-2.0-or-later.
+
+use Test::Most;
+use Test::Warnings qw(:report_warnings);
+use Mojo::Base -strict, -signatures;
+use FindBin;
+use lib "$FindBin::Bin/lib", "$FindBin::Bin/../external/os-autoinst-common/lib";
+use OpenQA::Test::Case;
+use OpenQA::Test::TimeLimit '10';
+use Test::Mojo;
+
+OpenQA::Test::Case->new->init_data(fixtures_glob => '01-jobs.pl');
+my $t = Test::Mojo->new('OpenQA::WebAPI');
+
+subtest jobs => sub {
+    $t->get_ok('/api/v1/jobs/23')->status_is(404)->json_is('/error', 'Job does not exist');
+    $t->get_ok('/api/v1/jobs/23a')->status_is(400)->json_like('/errors/0/message', qr{Expected integer - got string});
+
+    $t->get_ok('/api/v1/jobs/80000')->status_is(200)->json_is('/job/id', '80000')->json_is('/job/testresults', undef)->json_is('/job/priority', 50);
+    $t->get_ok('/api/v1/jobs/80000/details')->status_is(200)->json_is('/job/id', '80000')->json_is('/job/testresults', []);
+    $t->get_ok('/api/v1/jobs/99945?follow=1')->status_is(200)->json_is('/job/id', '99946');
+    $t->get_ok('/api/v1/jobs/99945?follow=2')->status_is(400)->json_like('/errors/0/message', qr{Not in enum list});
+
+    $t->post_ok('/api/v1/jobs/80000/prio', form => {prio => 99})->status_is(200);
+    $t->post_ok('/api/v1/jobs/80000/prio', form => {prio => 'not a number'})->status_is(400)->json_like('/errors/0/message', qr{Expected integer - got string})
+};
+
+done_testing;