4 ms·

What benefits does this provide over Swagger/OpenAPI? The ecosystem for OpenAPI is pretty rich - what is the intent here? Does it live with OpenAPI or replace

What benefits does this provide over Swagger/OpenAPI? The ecosystem for OpenAPI is pretty rich - what is the intent here? Does it live with OpenAPI or replace it?

martypitt 4y ago
Originally, Taxi was built because the readability / signal-to-noise ration of OpenAPI is pretty poor. Plus, we wanted to build a documentation spec that could automate integration - describe the specific contracts of what an API does, the data it exposes, and how and where that data can be leveraged in other APIs. You can't really read a swagger spec to get a sense of what it can do - you have to rely on tooling and UIs to make it understandable. For a toolkit who's entire purpose is documentation, that felt pretty frustrating. Also, in OpenAPI, you can't document how data attributes interact - ie., the specifics about what data an operation needs (beyond a map of Strings and Numbers). We wanted a way of saying "This operation accepts an Email Address, and returns an AccountBalance" that was machine understandable. However, you're right - the OpenAPI ecosystem is really rich, and we're not going to displace it. We've built Taxi extensions for OpenAPI[0] which allow you to embed the taxi type metadata directly inside OpenAPI specs. This helps with describing the interoperability (and is how tooling like Vyne[1] can automate orchestration between unrelated APIs) There's Swagger-to-taxi[2] tooling which will convert a Taxi schema to Swagger and back again - though this is more used internally to transpile OpenAPI on the fly. I doubt anyone will throw out their OpenAPI specs for Taxi - and that's ok. [0] https://docs.taxilang.org/generating-taxi-from-source/#swagger--openapi https://docs.taxilang.org/generating-taxi-from-source/#swagg... [1] https://vyne.co https://vyne.co [2] https://gitlab.com/taxi-lang/taxi-lang/-/tree/develop/swagger2taxi https://gitlab.com/taxi-lang/taxi-lang/-/tree/develop/swagge...

What benefits does this provide over Swagger/OpenAPI? The ecosystem for OpenAPI is pretty rich - what is the intent here? Does it live with OpenAPI or replace it?

martypitt 4y ago

Originally, Taxi was built because the readability / signal-to-noise ration of OpenAPI is pretty poor. Plus, we wanted to build a documentation spec that could automate integration - describe the specific contracts of what an API does, the data it exposes, and how and where that data can be leveraged in other APIs. You can't really read a swagger spec to get a sense of what it can do - you have to rely on tooling and UIs to make it understandable. For a toolkit who's entire purpose is documentation, that felt pretty frustrating. Also, in OpenAPI, you can't document how data attributes interact - ie., the specifics about what data an operation needs (beyond a map of Strings and Numbers). We wanted a way of saying "This operation accepts an Email Address, and returns an AccountBalance" that was machine understandable. However, you're right - the OpenAPI ecosystem is really rich, and we're not going to displace it. We've built Taxi extensions for OpenAPI[0] which allow you to embed the taxi type metadata directly inside OpenAPI specs. This helps with describing the interoperability (and is how tooling like Vyne[1] can automate orchestration between unrelated APIs) There's Swagger-to-taxi[2] tooling which will convert a Taxi schema to Swagger and back again - though this is more used internally to transpile OpenAPI on the fly. I doubt anyone will throw out their OpenAPI specs for Taxi - and that's ok. [0] https://docs.taxilang.org/generating-taxi-from-source/#swagger--openapi https://docs.taxilang.org/generating-taxi-from-source/#swagg... [1] https://vyne.co https://vyne.co [2] https://gitlab.com/taxi-lang/taxi-lang/-/tree/develop/swagger2taxi https://gitlab.com/taxi-lang/taxi-lang/-/tree/develop/swagge...