swakka | Scala library for creating Swagger definitions | REST library

Tip: if you create an API definition with dozens of endpoints, the AST is very complex. Each parameter for an endpoint is an element of a Params HList and each endpoint in an API is part of the Paths HList and every element requires JsonProtocol and RouteGen implicits in scope. If it does not compile, the Scala compiler will not help you determine which part of your code has the problem. Problems become harder to track down with the number of parameters and endpoints declared. You will end up having to hack your API definition down to a single endpoint and add each parameter, checking for compilation at each step before moving onto the next. Until you gain fluency, I recommend you develop your API step by step in the first place. This should keep the compiler on your side. Check the types of your parameters. Only body parameters support custom types. For QueryParameter, PathParameter and HeaderParameter Swagger only supports Int, Long, Float, Double, Boolean and String. For other types, the implicits required to serialize them to swagger json do not exist. Check there are no Optional PathParameters. They are not supported by Swagger/OpenApi. Make sure your endpoint implementation returns Route. It is a good idea to declare the endpoint type explicitly, e.g. ```val f: String ⇒ Route = …​```. Any other return type will break implicit resolution for the RouteGen. Check infered types for the OpenApi case class and the inner PathItems and Operations. If you have an implicit error, it is often worth putting in the type parameters explicitly. This can often transform a very daunting implicit error into a relatively harmless type mismatch. Check you have included the Swakka imports. Unless you need to get into low-level details, include the following imports 1) ```openapimodel.``` to bring in the swagger model case classes. 2) ```openapijson.``` to enable Swagger generation 3) ```coreroutegen.``` and 4) ```openapiroutegen.``` to enable Akka Http Route generation. If all these line up, the request will be accepted. The port does not matter. The simplest thing is to get the swagger route working (see above) and take a look at the generated swagger file. Remember, Swakka Routes do not check responses so the problem is always that something in the request does not match the API definition. Check the case of query and path parameters. They are case sensitive whereas headers are not. Check that parameters declared with required=true (i.e. non-option types) are all present. Finally, as for the swagger file, check the host header, scheme, base path and url all marry up with the api definition.