I'm not convinced that it is useless for all community developers who might want to consume APIs - I suspect their needs, backgrounds, and desires are more varied and hard to predict. There may be other possible benefits (such as complexity analysis, linting for guidelines compliance, etc.) Also, the one compelling benefit noted, documentation, is a Really Big Deal.
This is what I meant by solution in search of a problem. All of this sounds really compelling; It sounded compelling 20 years ago when Microsoft reps pitched it (WSDL), and it sounded really good 6 years ago when we went all-in with Swagger (aka OpenAPI), but no one was really asking for any of this, and none of these things ever materialized (documentation notwithstanding).
Agreed that this is an unhappy coupling. I'm not familiar with the RESTBase challenges mentioned, and I'd like to learn more. I'm curious whether this is inherently and overwhelmingly negative, or whether awareness of this issue could help us avoid/mitigate it in future efforts. We're in the process of preparing an API Guidelines document, which could be a cross-org place to guide best practice.
RESTBase's application configuration and its OpenAPI specification are one in the same. The very same YAML-formatted file that defines the OpenAPI spec, is also used to configure metrics, logging, and database connection parameters. This as akin to hard-coding configuration in application source (and so yes, inherently and overwhelmingly negative). I'm not sure when this decision was made, but I can definitely see how we got there, (I assume it was what resulted in the least duplication).
If you want to see an easy to grok example, look at Kask. Kask's OpenAPI spec was contrived to avoid as much of this as possible, eliding everything problematic that wasn't required by the specification. We also used very generic values for info.title and info.description, which we do not change for each deployment (which goes against the spirit of those attributes). Finally, the specification uses templating to inject a path that is set on a per deployment-basis in the application config.
Automated integration testing, even at a basic level, seems worthwhile. Is the objection to (1) creating our own extension, (2) the specifics of how we did it, or (3) something else?
I agree, automated integration testing is very worthwhile, but these tests are not written in any programming language, nor do they use any of the many well established test runners, they are written in our own DSL, embedded into the OpenAPI specification (see Kask's for an example), and executed via Service-checker. Presumably any standard integration test that we write could be automated as easily, would be vastly more capable, and could be parameterized so that we aren't (once again) tightly coupling deployment-specific things like request parameters and expected response values into what would otherwise be treated the same as code.
Service runner has been around for a number of years, so we could revisit available options to see if there's a less bespoke way of accomplishing this goal that would satisfy our needs.
Any chance you're confusing Service-runner with Service-checker?
Agreed that OpenAPI isn't an original idea and that many others have come and gone. But it does seem to be the current industry consensus and I'm not aware of a good alternative. If we don't use it, we risk fostering a not-invented-here mentality of custom solutions, having difficulty interacting with non-WMF developers accustomed to OpenAPI as an org-independent way of representing specifications, and missing out on opportunities to leverage available tooling from the larger API community.
Is it industry consensus? I never got the feeling that it ever gained that much traction. I know that if you go looking, you can find people that are using it, but my gut was that uptake was pretty...underwhelming. Of all the people in my circles, I seem to be the only one working for an org that has adopted it (anecdotal, of course).
Also, to be clear: My preference here is primarily that we stop drinking the Kool-aid. We've all but mandated that every service come equipped with a fully compliant OpenAPI specification, that the specification be published (via the service), and that it contain the aforementioned x-amples stanza in order to have service availability monitoring. Setting aside the awfulness of us creating our own integration testing grammar and test runner, is that even practical in a world where services are wired up to a public-facing gateway via Envoy? What sort of hoops are we going to have to jump through so that each service can publish it's own compliant spec, and the spec for the aggregate work can be published at the gateway (my point being, it wasn't made to work this way).
If the problem is documentation, and if swagger-ui produces documentation we're happy with, then services could include a subset of OpenAPI (the bits that correspond to the interface) which could be used to generate documentation (either for stand-alone services, and/or the gateway). They could also be used as input for things like linting if those use cases ever manifest. All of the actual problems we have can be solved with a machine-parsable representation of the interface, and by all means, there is no need for us to invent our own if that aspect of OpenAPI will suffice.
