Redocly/create-openapi-repo

Support for OpenAPI v2?

gchan opened this issue · 4 comments

gchan commented

I had a play with v3.0.3 and it appears OpenAPI v2 is not supported at the moment. If this is incorrect, any guidance on how to use this for OpenAPI v2 would be much appreciated.

I understand previously versions did support OpenAPI v2. Digging through the history it appears this npm packages used be to called generator-openapi-repo. What is the latest version of this tool which still supports OpenAPI v2?

adamaltman commented

Yes, only in the history of this repository.

d4343f1

The repository structure is for writing API definitions by hand. I really recommend you utilize the latest version of the spec to do that. OAS3 has been out for almost 3 years already.

gchan commented

Thanks for the info @adamaltman

We use the latest Ruby library Grape-Swagger however that currently only produced OAS2 :(

I'm currently looking at OAS2 to OAS3 converters so we can use the latest version of create-openapi-repo. Do you think that would be feasible? Would there be any compatibility issues between the two specs (I'm getting up to speed at the moment!)?

Ideally we would like to build an automated pipeline which publishes the latest documentation to Github pages :)

adamaltman commented

I don't think you need this repository if you're using code annotations. The purpose of this repo is for those who hand-author their API definitions.

Check out https://github.com/redocly/redoc to build the docs from your annotation-generated API definitions.

gchan commented

Thanks for the tip!

One of the 'nice to haves' is the ability to add supplementary documentation in Markdown. It seems this repo has some interesting tools to build/bundle multiple files into a single file. I'll take a look at https://github.com/redocly/redoc