Swagger 2.0

Swagger ist ein Opensource-Framework zur Unterstützung bei Design, Entwickelung, Test und Dokumentation von RESTful APIs.

Mit der Version 2.0 werden dazu die Module

  • Swagger Editor zum Design,
  • Swagger Build zum Generieren von Clients und Servern,
  • Swagger UI um Dokumentieren von Schnittstellen

angeboten.

Entwicklung der Service-Dokumentation mit swagger-editor

In meinem Fall lag das RESTful API auf Serverseite schon vor. Ich wollte dieses API für Konsumenten der Schnittstelle dokumentieren. Dazu bietet sich das Javascript-basierte Module swagger-editor an.  Die Installation erfolgt einfach:

Von github.io wird das Projekt https://github.com/swagger-api/swagger-editor heruntergeladen, anschließend werden die notwendigen rpm-module mittels

$> npm install

installiert. Durch Aufruf von

$> npm start

wird dann der webbasierte Editor aufgerufen.

Darin wird die Beschreibung des RESTful-API entweder in einer JSON-Struktur oder in der YAML-Schreibweise festgelegt. Die API-Definitionen können dort interaktiv getestet werden – einfach großartig, wie schnell man dort einen Überblick über sein API bekommt.

Ist die Definition der Schnittstelle – hier einen Clients – abgeschlossen, wird diese als JSON- oder als YAML-Datei auf einem Web-Server bereitgestellt.

Bereitstellen der Service-Dokumentation in Swagger-UI

swagger-editor ist ein Editor zum Entwickeln der Service-Beschreibung. Diese Modul ist nicht geeignet, um den eigenen Service für andere zu dokumentieren – in diesem Fall sollte die Service-Schnittstelle nicht mehr veränderbar sein.

Genau diese Zweck erfüllt das Modul swagger-ui, welches man ebenfalls von github.io herunterladen kann.

Hat man dieses Modul heruntergeladen, so muss man noch den Verweis auf die zu testenden Schnittstelle eintragen.

Dazu ändert man in dist/index.html den Verweis auf die weiter ob bereitgestellte eigene swagger.json -Datei.

Anschliessend lädt man den ganzen swagger-ui-Ordner auf den gewünschten Web-Server.

Repeatable Migrations mit Flyway 4.0

Flyway ist ein Datenmigrations-Tool und stellt mit der neuen Version 4.0 die „repeatable Migrations“, also wiederholbare Migrationen vor.

Wiederholbare Migrationen sind z.B. Definitionen von Views, Prozeduren, Funktionen und Packages, die, auch wenn sie sich verändern, nicht als Differenzskript, sondern als komplette Definition in die Datenbank eingespielt werden. Vor allem aber ist es so möglich, unter Beibehaltung des Dateinamens mehrere Versionen der Datei mittels Flyway in die Datenbank einzuspielen.

Anwendungsbeispiel

im Schema hr liefert die view Managers eine Sicht auf alle Mitarbeiter, die als Manager tätig sind.

Diese View ist in der Datei R1__View_Manager.sql definiert.

create view manager as select id,name from employees

Nun wird die Tabelle employees um eine Spalte isManager erweitert. Das Skript dazu steht in V1.1__manager_add_isManager.sql

alter table employees add isManager char(1) default 'N';

Entsprechend muss sich die View-Definition ändern. Diese Änderung erfolgt in der Datei R1__View_Manager.sql:

create or replace view Manager as select * from employees where isManager = 'Y'

Es ist dieselbe Datei wie die ursprüngliche Definition. Auf diese Weise lassen sich Änderungen an der Datei z.B. in GIT gut nachverfolgen und der Entwickler ist nicht mehr gezwungen eine weitere Datei mit der neuen Definition der View anzulegen. Das ist eine echte Verbesserung bei der Wartung und Entwicklung datenbankseitiger Logik.

utplsql mit gradle

In diesem Artikel stelle ich vor, wie utplsql mit dem Build-Automatisierungstool gradle integriert wird. Dazu verwende ich das utplsql-Plugin für gradle.

Die Aufgabe ist, die Tests für die Funktion btwnstr aus der utplsql-Dokumentation im Package ut_btwnstr über das Plugin in gradle auszuführen und die Testergebnisse darzustellen.

Vorgehen wie folgt:

Neuen Ordner anlegen

mkdir utplsql01
cd utplsql01

Gradle projekt initialisieren

gradle init

Die build.gradle-Datei wie folgt anpassen

buildscript {
  repositories {
    maven {
  url 'http://dl.bintray.com/iwarapter/gradle-plugins/' 
    }
  }
  dependencies {
    classpath 'com.iadams:gradle-utplsql-plugin:0.1.3'
    }
  }

apply plugin: 'com.iadams.utplsql'

repositories {
  mavenCentral()
}
dependencies {
  junitreport 'org.apache.ant:ant-unit:1.9.4'
}

task loadDriver {
  URLClassLoader loader = GroovyObject.class.classLoader
  loader.addURL (file ('lib/ojdbc6.jar').toURL())
  java.sql.DriverManager.registerDriver(loader.loadClass ('oracle.jdbc.OracleDriver').newInstance())
}
utDeploy.dependsOn loadDriver
utRun.dependsOn loadDriver

utplsql {
  url = 'jdbc:oracle:thin:@entw01:1521/orcl'
  username = 'hr'
  password = 'oracle'
  sourceDir = 'src/tests'
  includes = '**/*.pks, **/*.pkb'
  excludes = ''
  outputDir = 'build/utplsql'
  testMethod = 'run'
  setupMethod = true
  failOnNoTests = true
}

Nun einen src/tests Ordner anlegen

mkdir -p src/tests
cd src/tests

und darin die Source des Test-Packages ut_btnwstr kopieren.

Nun muss man noch einen lib-Order anlegen, in den der jdbc-Treiber kopiert werden muss.

mkdir lib
cd lib
cp /oracle-lib-folder/ojdbc6.jar .

Nun kann man mit

gradle utDeploy utRun

die Tests einspielen und ausführen.

Im nächsten Post zeige ich, wie ich dies für Continuous Integrations optimiere und erweitere indem flywaydb integriert wird.

utplsql – Unit-Testing für Oracle

Unit-Testing ist in vielen Programmiersprachen und -umgebungen ein etablierter Standard zur Qualitätssicherung in der Software-Entwicklung, nicht jedoch unter PL/SQL.

Über die Gründe dafür kann ich nur spekulieren. Vielleicht liegt es daran, dass der Entwickler die Technik (Abfragen, schreibende Zugriffe) nur sehr schwer von der Geschäftslogik trennen kann.

Letztlich gibt es m.E. keinen wirklichen Grund, Unitests unter PL/SQL zu unterlassen.

Im folgenden möchte ich die Technik und Tools vorstellen und einen Working-Prototype für einen einfachen PL/SQL-Unit vorstellen.

Dazu verwende ich utplsql, welches schon seit vielen Jahren Unit-Tests unter Oracle ermöglicht. In einem ersten Schritt starte ich den Unit-Test per Shell-Script.

In einem weiteren Schritt stelle ich ein Plugin für das Build-Tool gradle vor, mit dem der Test angestossen wird.

Installation von utplsql

utplsql wird nach Dokumentation installiert und kann anschliessend von allen Usern der Datenbank-Instanz verwendet werden.

Zum Test, ob utplsql richtig funktioniert, folgen wir dem Beispiel auf der utplsql-Homepage und definieren die Funktion

create or replace FUNCTION betwnStr (
 string_in IN VARCHAR2,
 start_in IN INTEGER,
 end_in IN INTEGER
 )
 RETURN VARCHAR2
IS
BEGIN
 RETURN  SUBSTR ( string_in,start_in,end_in - start_in + 1);
END;

Als Test-Package verwende ich ebenfalls das Beispiel von der utplsql-Seite. Das Testpackage hat den Namen ut_btwnstr und definiert einen Test:

create or replace PACKAGE ut_betwnstr
IS
 PROCEDURE ut_setup;
 PROCEDURE ut_teardown;
 PROCEDURE ut_BETWNSTR;
END ut_betwnstr;

Der Body mit der Test-Implementierung lautet:

create or replace PACKAGE BODY ut_betwnstr
IS
 PROCEDURE ut_setup IS
 BEGIN
   NULL;
 END;

PROCEDURE ut_teardown
 IS
 BEGIN
   NULL;
 END;

PROCEDURE ut_betwnstr IS
BEGIN
 utAssert.eq ('Typical valid usage',
    BETWNSTR(  STRING_IN => 'abcdefg',
               START_IN => 3,
               END_IN => 5),
    'cde');
 END;
END;

Somit haben wir einen Test definiert, den wir aus sqlplus aufrufen:

Begin
 utplsql.test (
     samepackage_in => false,
     package_in => 'betwnstr',
     prefix_in => 'UT_',
     recompile_in => false);
End;

Wichtig ist hierbei, dass utplsql eigentlich immer als Aufrufparameter den Namen des zu testenden Objekts fordert – also nicht den Namen des Testpackages!

Es gibt sicher noch andere Möglichkeiten, diesen Aufruf zu formulieren, die Ausgabe ist immer:

SQL*Plus: Release 11.2.0.3.0 Production on Thu Mar 17 18:15:43 2016
Copyright (c) 1982, 2012, Oracle.  All rights reserved.
Connected to:
Oracle Database 12c Enterprise Edition Release 12.1.0.2.0 - 64bit Production
With the Partitioning, OLAP, Advanced Analytics and Real Application Testing options
.
>    SSSS   U   U   CCC     CCC   EEEEEEE   SSSS     SSSS
>   S S  U   U  C C   C C  E     S   S   S    S
>  S     U   U C   C C   C E     S     S
>   S     U   U C     C     E     S       S
>    SSSS   U   U C     C     EEEE      SSSS     SSSS
> S  U   U C     C     E   S   S
>   S U   U C   C C   C E   S     S
>   S S   U U   C C   C C  E     S   S   S    S
>    SSSS     UUU     CCC     CCC   EEEEEEE   SSSS     SSSS
.
SUCCESS: ".betwnstr"
.
> Individual Test Case Results:
>
SUCCESS - betwnstr.UT_BETWNSTR: EQ "Typical valid usage" Expected "cde" and got
"cde"
>
> Errors recorded in utPLSQL Error Log:
>
> NONE FOUND
PL/SQL procedure successfully completed.
Disconnected from Oracle Database 12c Enterprise Edition Release 12.1.0.2.0 - 64bit Production
With the Partitioning, OLAP, Advanced Analytics and Real Application Testing options

Die Testausführung hat geklappt, die Tests waren erfolgreich.

Im nächsten Artikel geht es dann um die Integration von utplsql in das Build-Tool Gradle.