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. * 400 - Bad Request.If you don’t know Swagger, Swagger is a tool for documenting REST APIs. **Below is the list of HTTP Status code this API may return** _Below is the list of valid status of the Pet_ It is possible to mix the delimiters, which create the same results.įinally, let's place all this together into a YAML: /pet/findByStatus: Note the mix and match of the delimiters. Generates an unordered list with a sub-list. Similarly, to generate unordered sub-lists, indent the items with their parent item and start with a * (asterisks) or + (plus) or a – (hyphen). All the above snippets generate an unordered list.

Start swagger editor