Swagger/OpenAPI vs prmd?

[dmathieu]

I have been discussing this with several people, and I know there's been additional discussions as well, so I want to start a formal one here.

prmd is quite good, but we're the only ones maintaining it. OpenAPI and Swagger have been getting more and more visibility recently, and using them would make a lot of sense as well as facilitate documentation.

[dmathieu]

My thinking is that it wouldn't cost us much to support both prmd and swagger right now, and to build tools making migrations (from prmd to swagger, not the other way around) easier.

[geemus]

Yeah, OpenAPI/Swagger 2.0 addressed many (if not all) of the concerns I had which made me hesitant to adopt as we undertook prmd initially. With that out of the way, as well as a much broader ecosystem of support than it had at that time, I would feel much more comfortable with it (and alleviating the burden on us to maintain this, instead helping the broader community seems like a big win). I definitely think providing some good migration mechanisms would be a great next step to better explore if swagger will be sufficient (and to make it easier to move in that direction if it is, leaving us a nicer story about perhaps not having this support burden).

[brandur]

Right on. Although the API description space is still far from having a total winner, more recent developments have had the effect of making OpenAPI more attractive (opening the Swagger spec and support from the Linux Foundation), while adoption and continued development of Hyper-schema has been middling at best. I'd make the case that moving in the direction of OpenAPI spec is the right thing to do for the Pliny project and any organizations interested in having a published API description.

The good news here is that JSON Hyper-schema and OpenAPI spec look very much alike in that resource descriptions are JSON Schema, so some kind of programmatic conversion from one to the other should be possible pretty readily.

It's also worth nothing that with its relative popularity and healthy ecosystem of tooling OpenAPI spec may be the best option out there, but that doesn't necessarily mean that we'll have good replacements for everything we're currently doing with JSON Hyper-schema. I've done a bit of investigation in the area, and although its tooling is impressively prolific, a lot of it is quite heavyweight. I'm planning on building OpenAPI spec support into Committee to ease transition in its domain of responsibility.

As a final thought, if we could get a few notable companies like Heroku and Stripe onto OpenAPI spec, it might also go a long way toward helping to cement its leadership. IMO, this is something that would be very beneficial to the API community at large.

[gudmundur]

These discussions have been going on OOB in several places. It does feel that prmd, heroics and committee haven't been getting as much love as they used to, so I'm +1 for exploring this.

[geemus]

@brandur 👍 that aligns with my thinking and research as well. Just let me know if I can help support the committee or other work.

[tsrivishnu]

The good news here is that JSON Hyper-schema and OpenAPI spec look very much alike in that resource descriptions are JSON Schema, so some kind of programmatic conversion from one to the other should be possible pretty readily.

@brandur @geemus I have been trying to find some tools that could help migration from JSON Hyper-schema to OpenAPI spec. Are there any that you could share?

[brandur]

@tsrivishnu I don't know of anything like that personally, but pretty much the entirety of the resource/object section should be transcribable directly, and you just have to massage the API endpoint list somewhat. I've written two private OpenAPI generators now for my last two companies and I'd estimate they took me ~4 hours a piece — so it's definitely a bit of a project, but a relatively small-ish one.

[geemus]

@tsrivishnu Yeah, similar for me. I don't know of a generic solution available for this, but it should hopefully be fairly straightforward to address it directly in a particular case.

[tsrivishnu]

Alright. Thank you. I guess we will be building a migration script to perform our migration.

…

On 8. Aug 2022, at 18:18, Wesley Beary ***@***.***> wrote:  @tsrivishnu Yeah, similar for me. I don't know of a generic solution available for this, but it should hopefully be fairly straightforward to address it directly in a particular case. — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.