Openapi 3.0 [DRAFT]

[blakepettersson]

This is an attempt to address #603. OpenAPI 3 is quite different from Swagger 2, which leads to a couple of issues with this PR.

• This PR depends on a patched grape-swagger-entity (which is not in this PR)
• bundle exec rake DOES NOT currently work, since there's currently an issue with running the Swagger 2 and OpenAPI 3 tests at the same time...
• Currently the Group Array Params specs as well as the Mounted spec for OpenAPI 3 are not working (that can be addressed though)

In short, given how different OpenAPI 3 is from Swagger 2, it might be worth having a separate project for this, especially since we need to have a version of grape-swagger-entity that's works with OpenAPI3 (which implies that the same time that it won't work for Swagger 2).

It was a while since I worked on this, so there are for sure some other issues with this code, which I'll try to address once I remember what I've done.

[swistaczek]

Great work! 🤞for future work landing in upstream!

[LeFnord]

Hi @blakepettersson … many thanks for the great work 😄

I've created a oapi-3 branch, and re-target it gainst it

[LeFnord]

ok … let us mörge it

[gkirill]

Guys, sorry, any suggestions how to enable that? By default it seems to be using 2.0

[LeFnord]

use it in your Gemfile by specifying the repo and branch → https://bundler.io/guides/git.html

[eistomin]

@LeFnord , can i help you with master tree merging(ruby-grape:oapi-3 -> master or vice versa)?

[run27017]

It stills not merged into master?

[j-monteiro]

Are there any plans to merge this into master?

[EugeneIstomin]

Hi all!
Can we update & merge this branch? It would be like a 2-3 devs collaboration in upditing, merging, testing.

[synth]

Would love to see more official support! In the meantime, I thought I would post a workaround we discovered.

There is a converter:

• Online: https://converter.swagger.io
• Github: https://github.com/swagger-api/swagger-converter

Credit: https://stackoverflow.com/questions/59749513/how-to-convert-openapi-2-0-to-openapi-3-0

The way we are handling this is to convert our swagger2 spec during CI/CD and write a new file that is referenced by swagger-ui. It's really simple, we use Rails and RestClient, but feel free to adapt to your case.

https://gist.github.com/synth/1ea04df70fdb0d1af470394e3a4ae290

require 'restclient'

class OpenapiConverter
  CONVERTER_URL = "https://converter.swagger.io/api/convert"
  CONVERTED_FILE_PATH = File.join(Rails.root, "/public/api/docs")
  CONVERTED_FILENAME = "swagger-spec-v3.json"
  LOGGER = Rails.logger

  attr_accessor :url
  
  def self.convert(url)
    new(url).convert
  end

  def self.convert_and_write_to_public(url)
    converted_api = convert(url)
    full_filename = "#{CONVERTED_FILE_PATH}/#{CONVERTED_FILENAME}"
    File.write(full_filename, converted_api)
  end

  def initialize(url)
    @url = url
  end

  def convert
    full_url = "#{CONVERTER_URL}?url=#{CGI.escape(url)}"
    RestClient.get(full_url).body
  end

end

[LeFnord]

feel free to improve it … one can use it via:

gem 'grape-swagger', git: 'https://github.com/ruby-grape', branch: 'oapi-3'

[synth]

@LeFnord Thanks - However it seems to not have been updated since 2019 and the build is failing. While I don't have the time to work on this, my company would happily sponsor a developer to bring this work current.