If the service provider adds a new element to the list, which means adding a new element to the enum, your code will break when deserializing the payload if you don’t re-generate the client model. In this way you end up with hard-coded values of what it was supposed to be a dynamic list. However, when you generate the Java code out of the YAML, it generates the corresponding Java enums. When I started using Swagger I thought the purpose of this was that you can see all possible values an enum has in the Swagger UI. The problem of code generation with Swagger makes itself more evident with the enum type. If you implement the tolerant reader pattern correctly, modifying the payload – i.e adding a new element – should not break the client code. This is known as the Tolerant Reader Pattern . It also means, that you should not make any assumption regarding the structure of the payload. This means, you should only consider, or read, the elements in the payload that you need and ignore anything else you don’t. Here is the thing though: When consuming a REST API you want to be as tolerant as possible. It is actually seen as a productivity boost.
Code generation and deserialization.Īt first glance there is nothing wrong with code generation. However there are many problems that arise with this behavior. People think the YAML file is the new XSD, which means they treat the YAML file as a schema and just want it to generate the client model. Nevertheless I have seen it in several projects. This is a Swagger misusage problem, not a problem from Swagger per sé. The problems I am going to describe in this post happen in the context of documenting REST API using JSON and Java. However, I have observed that the usage is a common pattern, so although it is not a proper Swagger limitation, the tool tends to promote that kind of usage. Some of the problems presented here are known Swagger’s limitations, some other are more related to how people use Swagger. The documents are written in YAML, which I call XML for lazy people 😉īefore we continue I want to clarify that this post is based on personal experiences with Swagger. If you don’t know Swagger, Swagger is a tool for documenting REST APIs.
0 kommentar(er)
