What good is a tool if you don’t know how to use it?
… and the same goes for web services. Without a good documentation on how to use the provided web service the value of that web service is lowered massively. In the worst case it is not usable at all.
But instead of writing pages of unstructured prose about the web service the well established standard OpenAPI should be used as it is very well known in the web development world and has lots of tooling support. OpenAPI originated at Swagger which offers extra tooling for OpenAPI, f. e. an online OpenAPI editor and the Swagger UI project.
The most common format for providing an OpenAPI document is YAML and JSON.
But hey, YAML and JSON are data exchange formats. I thought we should write a documentation?!?
Yes. But 99% of web services today are using HTTP and HTTP has a well defined structure and syntax. So for many parts of the documentation you just have to enter some keywords. The rest will be generated.
Hint: You can see how your OpenAPI document looks like in web UI with the Swagger OpenAPI editor. It also shows you any syntax errors you might have in your document.
Where to start?
More or less the OpenAPI document has 3 main parts: common description, paths and components (data model).
Depending on the tooling you might want to take an existing document and edit that one. The petstore example is a good place to start.
Ways to Integrate
You have your OpenAPI document finished. Now what?!
Again … depending on the tooling you use you may want to provide the OpenAPI document via the
web service framework (ILEastic in our case). An easy way to do it is to write your own /openapi
endpoint / route procedure and simply call il_servceStatic. This will write the content of a
stream file (your OpenAPI document residing in the IFS) to the stream returned to the client
(f. e. Swagger UI).
That sounds good but now you need to deploy the program object to the target server and the stream file. That is doable and most change management systems support that but it is more complicated as it needs to be.
ILEastic OpenAPI static plugin to the rescue!
ILEastic provides a plugin for generating and serving the OpenAPI document, openapi-static.
The tooling provided by this plugin lets you generate an ILE module from the OpenAPI document. This module has no functions or procedures. It just contains the content of the OpenAPI document.
Now just add the generated ILE module and two modules from the openapi-static plugin to your
ILEastic web service program object and you are done. Everything is now contained inside your
program object and can be easily deployed to any IBM i server just by copying the program object.
Embedded OpenAPI
Another common way is to embedd OpenAPI snippets into your program code as comments. By doing this the documentation resides alongside your code and is also managed by any version control system used.
1 | // |
The openapi-static plugin provides the command OAPISRCGEN to parse one or more source stream
files on the IFS and extract the OpenAPI snippets from the source comments to a stream file on the
IFS. From there on it is the same procedure as previously by creating an ILE module from the
extracted OpenAPI documentation and adding it to the program modules of the program object.
This whole process is described in the README of the openapi-static plugin.
Hosting your own UI
Now you got your OpenAPI document(s) served by ILEastic but what now? A very convenient way of working with your OpenAPIs is to setup your own Swagger UI instance and configure your various OpenAPI documents there. This can be easily done with an Apache HTTP server instance on IBM i.
Wrap Up
ILEastic is a very flexible and extendable framework which can cover every needs the modern developer may have. If a topic is not covered yet it is often not very hard to implement it yourself.
Happy OpenAPI serving!
Mihael