Swagger and OpenAPI are very popular terms now a days. People building a new API want to use them. People working with legacy APIs want to use them too. Below i will be talking about some of the problems i faced when working with them.
As it is with a lot of other such standards, developing fresh using them is easier than migrating a legacy work. I recently worked on the later. ie exposing OpenAPI specs for a legacy API , which has 50+ versions supported in live production. For which we(me and my team) ended up generating the spec file ourselves, creating the required schemas in the required syntax.
One general issue i noticed was that OpenAPI treats all path parameter as mandatory/required by default. And it does make sense as otherwise the operation is technically a different operation, but sometimes, like in my case, we have optional path parameters. In such cases, the spec files are not 100% correct as per the operation.
One important part of such an activity is to ensure the generated file are OpenAPI valid. As there is no readily available jar/maven-plugin that would support OpenAPI v3, i had to build our own. (The one that did support v3 did not validate multiple files)
This is a minor (sometimes not so minor) problem with OpenAPI v3. A lot of available tools have not come around to support v3 yet. Last i checked, springfox was also not supporting it. Springfox is extremely helpful when building spring applications with swagger and OpenAPI.
I used swagger-parser-core 2.0.19 to validate the specification files. Simply put :
OpenAPIParser parser = new OpenAPIParser();
ParserOptions options = new ParserOptions();
SwaggerParserResult result = parser.readLocation(path, null, options);
swagger-parser library actually works well, but sometimes gives false positives. There is a known issue (#982) in its github repository that it fails to validate $ref when inside a path parameter. It only checks $ref value is provided, but does not validate if the reference actually exists in the provided schemas/parameters.
Next, i tried to generate a client (in java and spring) out of the specification. I used swagger codegen client cli v3.0.18. This has some of its own issues, which i will be highlighting below.
Following java naming conventions — If we have parameters / schemas defined with names starting with a digit (eg. 2DSquare) and they become java classes in the resulting client code, then the codegen library is unable to provide a correct naming convention. And as a result, of course the client doesn’t compile. Though the problem is easy to solve, by prefixing the name or rewording it.
Escaping regex patterns — the codegen jar was unable to escape the regex patterns (given when describing the schemas) properly when generating a spring client. Surprisingly this was not a problem with the java client. But the resulting client failed to compile and i had to manually escape the regex forward slashes. This is also an open issue listed in their github (#9509)
Defining BigIntegers — As we had generated the specification files ourselves, we had defined BigIntegers as Integers (swagger data type) with a proper max and min values. Java client was considering them as long, but spring client maintained them as integers. As the max limit was more than Integer.MAX, this failed spring client compilation. As a fix, i had to add
“format” : “int64”
to the schema definition.
I consider these problems very minor, when compared to the benefits OpenAPI and swagger bring to the table. The ease of swagger editor for modifying the spec and testing; and that of the codegen library to generate the client is amazing. And am sure these issues will be resolved in the near future.