[mendelk]

This is precisely the purpose of the OpenAPI Specification[0], an extended subset of the JSON Schema specification. Plus there a whole family of supporting tools, such as Swagger UI[1], and lots more[2].

[0] https://swagger.io/docs/specification/about/

[1] https://swagger.io/tools/swagger-ui/

[2] https://openapi.tools/

[acemarke]

Some searching turns up some articles on incompatibilities between OpenAPI and JSON Schema [0] [1], and it's not immediately clear if they fit together well at this point.

We've got some JSON Schema APIs in our services already and are using libs like the Python `json-schema` package to do validation with those. I also briefly experimented with Quicktype [2] to generate some TS types as a proof-of-concept.

We're getting ready to do a pretty big rework of a lot of our services, and I'm interested in any info folks can provide on pros and cons of using OpenAPI vs JSON Schema for API definitions, and tooling around request validation and TS interface / client generation.

[0] https://philsturgeon.uk/api/2018/04/13/openapi-and-json-sche...

[1] https://github.com/OAI/OpenAPI-Specification/issues/1532

[2] https://quicktype.io/typescript/

[yxhuvud]

The choice to fork[1] the schema standard instead of simply using it as is or with purely additive extensions) is so incredibly damaging. Yes, I get that it makes it a lot simpler to generate code for languages that have bad and static type systems. Meanwhile, the standard is still not powerful enough to describe everything JSON:API thinks is best practice due to not having any way to describe nested properties in queries.

[1] They don't want to call it a fork, but when they invent totally new extensions to support things that already is solved by parts of the standard that they don't want to support, then it is a fork.

[atombender]

One challenge around OpenAPI right now is that most of it is still stuck in version v2, with relatively immature support for v3. And v3 is quite different.

Not too long ago, I tried to build a project around OpenAPI, trying to generate model structs in Go from OpenAPI definitions. The support just wasn't there. There were code generation tools for v2 and emerging library support for v3, but nothing that covered both.

I went back and used plain JSON Schema for my models, and used GraphQL instead of OpenAPI for the API, and that turned out great.

[wing328hk]

Please give it a try with OpenAPI Generator (https://openapi-generator.tech), which supports both OpenAPI spec v2 and v3 for code generation.

[smt88]

V3 support is good these days for most languages. It's a delight to generate TypeScript types and then have the compiler tell you all the places you need to change code because your schema changed.

[why-el]

We went with this exact approach in my previous job, using OpenAPI to do everything the blog post mentions, including code generation, diffs for API consumers (published to Slack, for instance), and more. I believe this has a very good shot at success, but it's not complete yet. For instance we had to do a lot of in house work to make code generation work.

[handrews]

Hi- I'm one of the main editors of the JSON Schema specification, and one thing we are doing with the next draft is making it easier to build extensions for things like code generation. We expect to work with the OpenAPI folks on this as it is very relevant to their interests :-)

Also, we and the OpenAPI Technical Steering Committee are actively working together to re-converge the specifications. OpenAPI 3 was developed while JSON Schema progress was stalled due to the prior editors leaving and a new group of us (eventually) picking it up.

OpenAPI 3.1 will most likely include a keyword to allow using standard JSON Schema as an alternative to their customized syntax, and hopefully we can achieve full integration on OpenAPI 4. There are also some other ideas being explored for improved compatibility in 3.x.

Standards work is hard, but the relationship between the OpenAPI TSC and the JSON Schema editors is quite healthy and we are making good progress.

[nathan_f77]

I agree, I've also invested a huge amount of time and effort into my openapi-generator setup [1], and there's tons of room for improvement. We've probably even done some of the same work for code generation (custom Java subclasses, etc.)

[1] https://github.com/OpenAPITools/openapi-generator

[wing328hk]

Not sure which code generation tool you used but if you've time, please try OpenAPI Generator (https://openapi-generator.tech) and let us know if you've any feedback.

[royjacobs]

As someone who works with this tooling nearly daily I can tell you that OpenAPI is unfortunately quite messy.

It seems like Swagger v2 was reasonably well-liked so the idea was to make OpenAPI the best possible way to describe any kind of REST API in existence. Since the spec got more or less merged with JSON Schema it has become extremely unwieldy and full of edge cases.

At my company we're trying to develop tooling around OpenAPI but a lot of things (especially related to the 'oneOf'/'anyOf'/'allOf' features) are extremely ambiguous.

Not to mention that at least the Java versions of the parsing libraries are full of inconsistencies as well. For instance, there's a OpenAPI parser which also has a 'compatibility' mode so it can read Swagger V2 specs as well. Unfortunately the data you get from reading a Swagger V2 spec via that compatibility layer is different from when you'd first convert the V2 spec to OpenAPI v3 through an external tool.

The project is certainly ambitious and I completely agree that this is a hard problem to solve, but honestly I would say that if you want universal adoption of a toolkit for writing API's then the API specification language itself should not be so difficult or ambiguous in its implementation.

[nathan_f77]

I've really enjoyed working with OpenAPI / Swagger while building FormAPI [1]. I use rswag [2] to define and run a set of integration tests that test everything about the API, and then all the requests/responses/schemas are saved into a OpenAPI specification. I can then use that to generate API clients for any language [3]. Then I have test suites for each API client, which spins up the dev server and ensures that all the API calls have the correct behavior (to catch any bugs in openapi-generator, or my custom code that wraps some of the generated functions.)

It took a lot of work to get there, and there's still lots of room for improvement. My ultimate goal is to automatically generate the API client test suite based on the requests/responses. I also want to add some custom logic and workflow rules to the OpenAPI specification, instead of needing to write custom wrapper code in 10+ languages.

I've had to write the same basic code so many times: Make a POST request, then make a GET request once per second until the "status" changes from "pending" to "done", and then finally return the completed result. (I know it would probably be better to set up a websocket connection, but this works fine and it was easier to implement.) It would be so awesome if I could define this workflow inside my API specification, and then the auto-generated client code could include this polling logic without any effort on my part. (Apart from needing to write and support the higher-level generator code for each language, which would actually be a lot more work.)

The other really annoying thing is needing to figure out package managers and release steps for every single programming language. I've only figured this out for 6 languages so far (C#, Java, JS, PHP, Python, Ruby), but I want to support far more languages, and it's just exhausting to go through this process each time. It would be so nice if there was an open source project that wrapped all of the different package managers and provided a framework on top of openapi-generator. And if there was a CLI tool (or web UI) that walked you through the process of signing up for accounts and setting up API keys, and then keeping it all in one place. I would honestly be tempted to rewrite openapi-generator from scratch in a better language / template engine, because the Java code is so hard to read and extend. I'm mainly a Ruby developer, but I don't think Ruby would be a great choice for CLI / generator tools, because it gets pretty slow. So maybe Python or Go.

I feel like this would a really interesting project to work on, and potentially a startup idea. Would anyone be interested in using it? I should probably try to validate this idea. I've set up a Google Form where you can just click a checkbox to register your interest anonymously, or you can also submit your email if you want to get updates and try a beta version: https://forms.gle/7qWzWpC9QrTjUgnU7

[1] https://formapi.io

[2] https://github.com/domaindrivendev/rswag

[3] https://github.com/OpenAPITools/openapi-generator