openapi parser spec including files

[kurt...@moment-4.be]

Hey all,

I'm using the openapi spec with vertx 3.6.3. In the spec, I refer to other yaml files.

    SomeType:
      type: object
      description: some record
      properties:
        core:
          type: string
          enum: ['type1', 'type2']
          example: 'type1'
        type1:
          $ref: "./spec/type1.yaml#/Type1"
        type2:
          $ref: "./spec/type2.yaml#/Type2"

All works fine when I run it locally from my IDE (Intellij). However, whenever I build a fat jar (or a runtime), the included files are not found:

WARNING: Exception while reading:: java.lang.RuntimeException: Unable to load RELATIVE ref: ./spec/another.yaml path: /home/<some path>/swaggerroot
        at io.swagger.v3.parser.util.RefUtils.readExternalRef(RefUtils.java:183)
        at io.swagger.v3.parser.ResolverCache.loadRef(ResolverCache.java:118)
        at io.swagger.v3.parser.processors.ExternalRefProcessor.processRefToExternalSchema(ExternalRefProcessor.java:49)
        at io.swagger.v3.parser.processors.SchemaProcessor.processReferenceSchema(SchemaProcessor.java:201)
        at io.swagger.v3.parser.processors.SchemaProcessor.processPropertySchema(SchemaProcessor.java:102)
        at io.swagger.v3.parser.processors.SchemaProcessor.processSchemaType(SchemaProcessor.java:53)
        at io.swagger.v3.parser.processors.SchemaProcessor.processSchema(SchemaProcessor.java:38)
        at io.swagger.v3.parser.processors.ComponentsProcessor.processSchemas(ComponentsProcessor.java:222)
        at io.swagger.v3.parser.processors.ComponentsProcessor.processComponents(ComponentsProcessor.java:72)
        at io.swagger.v3.parser.OpenAPIResolver.resolve(OpenAPIResolver.java:50)
        at io.swagger.v3.parser.OpenAPIV3Parser.readLocation(OpenAPIV3Parser.java:53)
        at io.vertx.ext.web.api.contract.openapi3.OpenAPI3RouterFactory.lambda$create$1(OpenAPI3RouterFactory.java:164)
        at io.vertx.core.impl.ContextImpl.lambda$executeBlocking$2(ContextImpl.java:272)
        at io.vertx.core.impl.TaskQueue.run(TaskQueue.java:76)
        at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128)
        at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628)
        at io.netty.util.concurrent.FastThreadLocalRunnable.run(FastThreadLocalRunnable.java:30)
        at java.base/java.lang.Thread.run(Thread.java:834)
Caused by: java.lang.RuntimeException: Could not find ./spec/another.yaml on the classpath
        at io.swagger.v3.parser.util.ClasspathHelper.loadFileFromClasspath(ClasspathHelper.java:31)
        at io.swagger.v3.parser.util.RefUtils.readExternalRef(RefUtils.java:177)
        at io.swagger.v3.parser.ResolverCache.loadRef(ResolverCache.java:118)
        at io.swagger.v3.parser.processors.ExternalRefProcessor.processRefToExternalSchema(ExternalRefProcessor.java:49)
        at io.swagger.v3.parser.processors.SchemaProcessor.processReferenceSchema(SchemaProcessor.java:201)
        at io.swagger.v3.parser.processors.SchemaProcessor.processPropertySchema(SchemaProcessor.java:102)
        at io.swagger.v3.parser.processors.SchemaProcessor.processSchemaType(SchemaProcessor.java:53)
        at io.swagger.v3.parser.processors.SchemaProcessor.processSchema(SchemaProcessor.java:38)
        at io.swagger.v3.parser.processors.ComponentsProcessor.processSchemas(ComponentsProcessor.java:222)
        at io.swagger.v3.parser.processors.ComponentsProcessor.processComponents(ComponentsProcessor.java:72)
        at io.swagger.v3.parser.OpenAPIResolver.resolve(OpenAPIResolver.java:50)
        at io.swagger.v3.parser.OpenAPIV3Parser.readLocation(OpenAPIV3Parser.java:53)
        at io.vertx.ext.web.api.contract.openapi3.OpenAPI3RouterFactory.lambda$create$1(OpenAPI3RouterFactory.java:164)
        at io.vertx.core.impl.ContextImpl.lambda$executeBlocking$2(ContextImpl.java:272)
        at io.vertx.core.impl.TaskQueue.run(TaskQueue.java:76)
        at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128)
        at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628)
        at io.netty.util.concurrent.FastThreadLocalRunnable.run(FastThreadLocalRunnable.java:30)
        at java.base/java.lang.Thread.run(Thread.java:834)

How can I make relative paths work properly with fat jars/runtime builds?

Thx, Kurt

[Francesco Guardiani]

Unfortunately this is because of the parser that we use, swagger-parser. When you try to use intellij runner the reference is picked up from outside the classpath, while when you use the fat jar it search the ref inside the classpath. In the last swagger-parser update changelog i saw that they fixed some issues about relative refs loading, i try to update and i see if it's fixed. I'm tracking this issue here: https://github.com/vert-x3/vertx-web/issues/945

[kurt...@moment-4.be]

Allright, thx... only other solution I see is to copy/deploy the files at a fixed location somewhere. Could work as well.

Op vrijdag 29 maart 2019 11:19:44 UTC+1 schreef Francesco Guardiani:

[Francesco Guardiani]

You can also use a tool that does the building of the spec in one single file, i did some experiments some time ago. Using npm https://github.com/APIDevTools/swagger-cli tool I bundle the spec, then i included it in my maven lifecycle with  https://github.com/mjeanroy/node-maven-plugin. I try to write a tutorial on it asap