Openapi-specification: Way to denote inactive/beta endpoint?

[diogeneshamilton]

Hoping there is/will be a way to define the endpoint using Swagger, but denote that it has not been released yet. Have people thought of this already and just made the responses error out?

[webron]

There's only a way to denote an operation as deprecated, which is the post step, not the pre ;)

[diogeneshamilton]

Hmm, maybe it could be called beta or inactive

[webron]

There's no direct way to do that in the spec right now. Would you like to mark it as a feature request for future consideration?

As a workaround for now, you can use your own vendor extension to specify that on an operation ("x-beta": true for example).

[diogeneshamilton]

@webron yes, I think it's something that could make sense in the next version. I'll use an extension for now.

[jasimmonsv]

a label as experimental is what I was looking for. Just for consideration.

[ChristianLutz]

I would prefer either beta or experimental, both express what the purpose is. Adding such a label would allow plugins like swagger-brake to test for if the API still backward compatible better in this cases.

@webron Could you reopen this one?

[bkabrda]

👍 to reopen and add this. This would be an extremely useful addition and IMO can be added in a backwards compatible way.

[BelfordZ]

We've adopted the MethodObject field deprecated: Boolean. Seems like a reasonable addition for the inactive portion.

[bkabrda]

@BelfordZ yeah, deprecated is useful, but for my usecase, I need to use both deprecated (old, not to be used) and beta (new, possibly unstable and changing) endpoints. For now, we're going with using something like x-beta or x-unstable on individual operations. Long term, we'd like to see this in the openapi spec because we're heavily using openapi-generator and adding a code that would handle our custom specification extension is (understendably) no-go for that project.

[MikeRalphson]

@bkabrda Just for clarification, what changes in generated code would you expect for a beta or unstable operation? An annotation, logging etc?

[bkabrda]

@MikeRalphson what we do is quite opinionated - we do a downstream patch of openapi-generator templates that make the unstable operations raise exception unless they were explicitly enabled in the code that uses the generated client library. This is our mechanism of getting user consent on the fact that the unstable API might break. We also always log a warning when an unstable method is called (even when explicitly enabled).

I think the right approach to unstable operations is debatable, but openapi-generator allows parametrizing how the templates are rendered and that would give us enough space to do different things based on options given during code generation. So given how strict you want to be with your generated client library, you might want to use annotations or logging or requiring explicit user consent - or a combination of these.