Swagger-core: Add example of usage of openApiFile for swagger-gradle-plugin

[betrcode]

Tried to use the openApiFile configuration in swagger-gradle-plugin but couldn't figure out how to make it work.

It would be good if we could add an example of the usage in the README.

If someone can help figure out how to use it I can try to make a PR with the updated README.

[frantuma]

adding the input file path should be sufficient to have its content (typically info section and/or some components) used as input to the resolving engine and merged into result.

e.g.

resolve {
    outputFileName = 'out'
    outputFormat = 'JSONANDYAML'
    prettyPrint = 'TRUE'
    classpath = sourceSets.main.runtimeClasspath
    resourcePackages = ['my.package']
    outputPath = '/tmp'
    openApiFile = file('/tmp/input-openapi.yaml')
}

do you have problems with this approach?

[geekrumper]

I have the same issue. I can puposely configure gradle to not find the file (openapi-configuration.yam) and the expected result is printed:

• What went wrong:
  A problem was found with the configuration of task ':resolve'.

  File 'Q:............\openapi-configuration.yam' specified for property 'openApiFile' does not exist.

• Try:
  Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output.

• Get more help at https://help.gradle.org

BUILD FAILED in 7s
38 actionable tasks: 3 executed, 35 up-to-date

When gradle is configured correctly, no error is printed. Which means that the configuration file can be found. But still the content is not being merged at all. It doesn't matter if the configuration is YAML or JSON.

Here are the configuration examples that I used:

JSON

{
  "prettyPrint" : true,
  "openAPI": {
    "info": {
      "version": "1.0",
      "title": "Swagger Pet Sample App",
      "description": "This is a sample server Petstore server.  You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).  For this sample, you can use the api key `special-key` to test the authorization filters.",
      "termsOfService": "http://swagger.io/terms/",
      "contact": {
        "email": "[email protected]"
      },
      "license": {
        "name": "Apache 2.0",
        "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
      }
    }
  }
}

YAML

prettyPrint: true
cacheTTL: 0
openAPI:
  info:
    version: '1.0'
    title: Swagger Pet Sample App Config File
    description: 'This is a sample server Petstore server.  You can find out more
      about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net,
      #swagger](http://swagger.io/irc/).  For this sample, you can use the api key
      `special-key` to test the authorization filters.'
    termsOfService: http://swagger.io/terms/
    contact:
      email: [email protected]
    license:
      name: Apache 2.0
      url: http://www.apache.org/licenses/LICENSE-2.0.html

If something is wrong with the format, I would like to be notified by gradle. The gradle task is being executed with the --debug parameter, but I never was able to see any logs about the merging process.

[betrcode]

@frantuma Thanks for responding. I had the same issue @geekrumper describes above. I worked around in by not using that feature. Havn't tested it since. I will try it next time I need to setup Swagger for a project. (Don't have time right now.)

[geekrumper]

I don't think this issue can be ignored, since I get the following error in swagger editor:

Schema error
should have required property 'info'
missingProperty: info
Jump to line 0

We would like to use this solution for public documentation of our API. I know we can we have alternatives like producing configuration programmatically. But our goal is to reduce the amount of swagger code to an aboslute minimum. Therefore having an external configuration file referenced by gradle is prefered.

[betrcode]

My use case was primarily to keep the openAPI.info.version outside of the service code, and keep that part controlled by Gradle since it controls which version is being built.

[frantuma]

from the examples you shared, possibly the issue is that you are passing a serialized instance of SwaggerConfiguration, while the parameter accepts instances of OpenAPI (just the spec, not the config, the rest of the config is passed via task parameters). Can you give that a try?

[betrcode]

@frantuma Not sure I understand. Could you provide an example of a instance of the OpenAPI spec?

[frantuma]

it would be:

` openapi: 3.0.1 info: version: '1.0' title: Swagger Pet Sample App Config File description: 'This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key special-key to test the authorization filters.' termsOfService: http://swagger.io/terms/ contact: email: [email protected] license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html

[geekrumper]

Here's what I've tried:

build.gradle

resolve {
    outputFileName = 'API'
    classpath = sourceSets.main.runtimeClasspath
    outputPath =  "${buildDir}/api"
    outputFormat = 'JSONANDYAML'
    resourcePackages = ['com.example.package']
    prettyPrint = true
    openApiFile = file('openapi-configuration.json')
}

openapi-configuration.json

{
  "openAPI": {
    "info": {
      "version": "1.0",
      "title": "Swagger Pet Sample App",
      "description": "This is a sample server Petstore server.  You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).  For this sample, you can use the api key `special-key` to test the authorization filters.",
      "termsOfService": "http://swagger.io/terms/",
      "contact": {
        "email": "[email protected]"
      },
      "license": {
        "name": "Apache 2.0",
        "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
      }
    }
  }
}

As you can see, just like you mentioned only the openApi instance is provided. All other configuration properties are in my build.gradle and still no luck.

[frantuma]

This again doesn't map to an OpenAPI file, as it includes root openAPI, the right one in json format would be

{
  "openapi" : "3.0.1",
  "info": {
    "version": "1.0",
    "title": "Swagger Pet Sample App",
    "description": "This is a sample server Petstore server.  You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).  For this sample, you can use the api key `special-key` to test the authorization filters.",
    "termsOfService": "http://swagger.io/terms/",
    "contact": {
      "email": "[email protected]"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    }
  }
}

As I mentioned the expected file is not a Swagger configuration but a spec, I would therefore rename openApiFile = file('openapi-configuration.json') to something like openApiFile = file('openapi-input.json')

[geekrumper]

@frantuma you're absolutely right, that change did the trick! I guess this knowledge has to be reflected in the README, because atm it's only referring to configuration properties which does not mention openApiFile but rather openAPI and that's how many devs are being missguided to think that this file is the configuration. They also search for a configuration example and stumble upon the ones I mentioned before.

Also, thank you for your support.

[frantuma]

you're right, added a not to readme with example. Closing ticket, please reopen if you're still experiencing issues