We may say that OpenAPI is the latest craze on the field microservices. Otherwise it is also true that this specification helps a lot to implement standardised APIs. We gave it a try to implement our new portfolio element interfaces on OpenAPI basis and this article is to share to you our hands-on experiences. The results of the development, where we collected the expereinces below, will come soon.

Swagger editor

The first thing you will meet is swagger editor (read more about swagger - OpenAPI relation). This is the entry point to build your first api model, while you may change to use other editors which handles YAML format... later. 

If you made the first setup, you will have a kind of understanding about the concept and the editor. You arrived to the latest stage when you have to decide if you will use OpenAPI 2.0 or 3.0. I don’t want to waste keypresses about the comparison of the two, since there are so many great articles giving you all the details for the selection.

I still want give some extras focusing on the editor itself. If you select 3.0 then there is no question, you have to use swagger3.

If you select to stay on 2.0 then you can use both swagger2 and swagger3 editors. Swagger2 has the advantage that support so many color style schemes while 3 has only a single one. On the other hand swagger2 has so many stupid bugs, like the string formatting annotation is not working properly on each places; it is too sensitive about the order of element definitions and so. Swagger3 editor is more bug-less and supports swagger2 annotation. I suggest you to use the more fresh editor instead of the case you need the pretty color schemas.

OpenApi 2.0 or 3.0?

Except you need the new structure, which is enabled by 3.0 I strictly suggest you to use 2.0. The core value of swagger/OpenAPI is, that you can generate the interface code based on the API definition and 3.0 has far less generators ready to use comparing to 2.0.

Finally, if you decide to keep the direction of preparing API definition and generate the interface code your friend will be Swagger3 to define OpenAPI2.0 today.

We left this way…

Let’s see the reasons. The first, still not critical problem was the editor. I told you above that you will change to anything else where you will edit the YAML file containing the definition or will turn to JSON format on the same way and import each stage back to swagger - and learn praying if you cannot. Import does not help on the unexpected situations, but you will face less problem of editing using a stable text editor.

The real show-stopper was the code generator part, which is clearly incomplete! We wanted to use Java as we selected this language as the best fit for the application started to build. The structure of the code was fine, approving some not liked portion, but the real, unbelievable problem was that enumerations are empty. You define record statuses for example, which will be generated a RecordStatus class with no any values in it. This is a real showstopper, since the model stops working immediately. You may add the missing part into the code, but next time of generating the skeleton you would start it from the scratch. I would not call it generation of interface code anymore.

One more thing would be mentioned is, that enumeration must be simple a set of values, and cannot be enriched with extra attributes, like classification information, neither swagger descriptions are not possible to add to the values.

Opposing way, generate OpenAPI UI

We changed the direction and started to implement our APIs and the model using Spring framework. On this way there is no doubt that we will get a full-functional code but we then loose two thing. The first is the definition based API generation what ensured the proper package and class structure in the code. It can be managed as before, having smart developers. The other loss was more painful, since we lost the great Swagger-UI, which contains all the readable formatted information of the APIs and the model, including the API tester function, which composing the API requests and the formats the responses on a pretty readable way.

Luckily there is a great answer for the painful loss also, called SpringFox! It gives you the way of defining code annotations, what will be used as input to the swagger-ui, using all the same formatting rules as in swagger editor. It is a great extension, while it is not the friend of of enumerations either. I mean the model section will not contain the enumerations at all…

We arrived to simple question: would you generate improper codes or incomplete API documentation? We knew the good answer and implemented our solution in Spring with SpringFox. Maybe next time…

Enumeration

Enumeration of status codes in swagger:

The same enriched enumeration in „hand made“ java:

It is so important, that the whole code can cast the processing statuses under the hood, using this status, since the status includes the http response code, the message title and description together with a numeric code, which is the basis of status classification or client side message dictionary.

The status classification is a based on an embedded enumeration. If you compare the two approaches you will see that the „legacy“ way gives you much more opportunities two make self-documented code. Swagger really has the advantage that gives you a language independent approach but on the other hand it wants to be the superset of good old programming languages having years of history including successful and dead-end ideas.

I’d like to highlight the SpringFox annotations above. ApiModel will be a root element in the model section containing the description, while ApiModelProperty elements will be the input of field description. Either SpringFox does not generate enumerations into the model, the code contains all the necessary annotations preparing for the time when it will (or we will extend in in-house to handle by our needs only). Giving an example, here is a class which was defined on the same approach and contains ReactorStatus enumeration, and all its attributes separately.

I believe it is worthwhile to keep the directives would be tested and learnt by a first run of OpenAPI code generation but build and maintain your code manually. Keep it safe!