Providing a swagger for a rest service

Discussions relating to the ScottKlement.com port of the open source YAJL JSON Reader/Generator. This includes the YAJL tool as well as the YAJLR4, YAJLGEN, YAJLINTO and YAJLDTAGEN add-ons from ScottKlement.com. http://www.scottklement.com/yajl/
Post Reply
LUCAG
Posts: 7
Joined: Tue Mar 28, 2023 9:00 am

Providing a swagger for a rest service

Post by LUCAG »

Don't know if this is the right forum to ask for assistance, if i chose the wrong one i ask your pardon.
Few years ago I built up a rest api on my IBM i box to provide few services for my company website.
Requesting customer info and order status and other stuff like that, very simple to do since i recycled a ton of existing rpg programs within our enviroment.
The way I chose to do that is by following the DIY approach described in a bunch of Scott presentations.
I set up an http server and then built/modified exixting pgms to handle the requests e give the answer needed.
But there's one thing we really miss, the ability to build a swagger file for our API.
Now they want include such services in our mobile app, the developer of the mobile app ask me for the swagger of the services, but i ain't got one.
Is there a way to built a swagger or should i write a pgm that write a file on the IFS? Is there a way to know which information should be in the swagger?
TIA.
jonboy49
Posts: 200
Joined: Wed Jul 28, 2021 8:18 pm

Re: Providing a swagger for a rest service

Post by jonboy49 »

I have not had the opportunity to test drive it yet but I believe that Swagger Inspector is capable of doing what you need. https://swagger.io/docs/swagger-inspect ... inspector/

You can try it for free although the free account limits how many you can generate.

Let us know how you get on - this was on my "check it out" list but hasn't made it to the top yet.
Scott Klement
Site Admin
Posts: 636
Joined: Sun Jul 04, 2021 5:12 am

Re: Providing a swagger for a rest service

Post by Scott Klement »

YAJL doesn't, by itself, understand a swagger document -- you could use it to write your own swagger software, though, since the OAS is JSON-based.

But you might consider a commercial tool for Swagger.

The company I work for provides one called MDREST4i -- extremely powerful way to work with Swagger in RPG. It might be worth looking into...
https://www.midrangedynamics.com/rest-d ... ent-tools/
LUCAG
Posts: 7
Joined: Tue Mar 28, 2023 9:00 am

Re: Providing a swagger for a rest service

Post by LUCAG »

Thanks Jon e Scott for your reply.
@Jonboy49, i gave a quick look to the swagger inspector, it might work but requires the time to test all the methods within the api, and has not the capability to understand if a method is get or post or whatever, the user must tell which verb is used by a given method. In my scenario we have at least 30 methods with very simple json in and out, so it can be done well with swagger inspector, in larger scenario (or in a more complicated one) I don't know if this might be the right choice to go.
@Scott thx for your suggestion. But project like mine suffer from an original sin. They were build in a the way they were build mainly for the lack of budget (both time and money) to build an alternative. And they work very well even if they have such limitation like the missing of a swagger. But they work very well.
So I think I'll go first trying to build something of my own to produce a swagger for my service, and If you don't mind I'll write here how I am willing to go.
I read a few articles about swagger file, i understood that a swagger is a json file with a given structure.
There ae at least 8 main nodes:
1 swagger
2 info
3 host
4 schemes
5 basePath
6 tags
7 definitions
8 paths

1 is mandatory and must have as value 2.0 "swagger": "2.0";
2 is an array that give a human readable description of the service, the array contains 3 fields "title", "description", "version" (this can be done putting such info in a parameter of the command to create the swagger).
3 contains the url of the service (something like myapi.mydomain.mytld) this can be retrivied by the http configuration file or written in a parameter of the command to create the swagger)
4 must have a mandatory value of http "schemes": [ "http" ],
5 is the base path for the methods of the api, also this one might be retrieved from the http config file or as a parameter in the command to create the swagger. The output expected is something like "basePath": "/web/services/myapi",
6 another array with description fields "name" and "description" associated with the base path itself
7 is a nested array that contains the description of all the named variables and data strucutures used in the pgms' prototype. Each parameter/result returned by the becomes an array with three or more "fields": name, type, format, maxLenght, maxItems (in case you use a dim ds).
8 contains a series of array describing the various methods within the api.
the strucuture should be something like :
8.1 the verb (get, put,...)
8.2 tags (again an array containing a human readable description of the method i.e. "list invoice by shop")
8.3 operaionId (i.e. getInvoiceByShop)
8.4 consumes (this should be something like "*/*" or "json/json")
8.5 produces (this should be something like "application/json")
8.6 parameters (name of the input parameters and their format, type ecc ecc)
8.7 responses (another array with the main http error code 200, 401 and the expected for every response)
7 and 8 are the hardest part to build, the infos needed to build this part of the swagger may be retrieved from PCML file associated with the compile of the pgms and from the http's config file. Now I must fnd a way to work this informations from their sources and understand how to combine and trasform them.
Any suggestion wil be very appreciated.
TIA
Post Reply