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.

[takato1314]

Hi. Are there any plans for introducing this use case into the specification? As @MikeRalphson said the usage should be opinionated.

For example, I would expect perhaps something like this in my swagger ui display to indicate that a particular version of the API is still experimental and some note/message should be displayed just under the main heading of the document.

[pengying]

I'd like to have the granularity to mark paths or fields in objects as experimental or beta. I don't expect it to impact the library but would be handy to highlight in documentation services.

IMO would be useful to formalize x-beta -> beta or experimental

[lashchev]

I would prefer "experimental" as the term for unstable items (paths, operations, properties).
"Beta" in a lot of cases is considered as a "preview," and people usually expect API to "graduate" from beta status eventually.
"Experimental" clearly indicates that the future of this element is unknown - it can change in any way or disappear entirely.

[fgabolde]

I still want this feature, at the operation, parameter and schema level. Wherever deprecated makes sense, experimental would also makes sense, and like deprecated, it doesn't need to have actual behavior behind it, but standardizing it would allow tools to make use of it.

In particular, we are using https://github.com/OpenAPITools/openapi-diff (somebody earlier in the thread mentioned swagger-brake which was its spiritual predecessor, I believe) and we would like it to skip alerting if an experimental operation has changed.

[bdunavant]

Noting that I also found this thread because I am trying to work out how to mark something at experimental, so customers know that field/endpoint may mutate until we decide to support it long-term.

[kr99]

For now, I will probably just document the endpoint as GET /beta-2/things

[nicobao]

I still want this feature, at the operation, parameter and schema level. Wherever deprecated makes sense, experimental would also makes sense, and like deprecated, it doesn't need to have actual behavior behind it, but standardizing it would allow tools to make use of it.

In particular, we are using https://github.com/OpenAPITools/openapi-diff (somebody earlier in the thread mentioned swagger-brake which was its spiritual predecessor, I believe) and we would like it to skip alerting if an experimental operation has changed.

I have the exact same use case. For now, I'll attempt to use my custom x-experimental: true extension, and run openapi-diff programmatically (in a unit test) so that I can take this extension into account when calculating breaking changes.

[Welchen]

This feature would be very helpful. Either a beta or experimental tag.

[kevinforrestconnors]

I am also in need of a "beta" feature (we call it "under construction")

[ssavkovic]

Same here, we really need "Beta" tag for the new unstable endpoints.

[fkreis]

👍 Upvote for a beta/experimental tag!

[thbar]

Experimental would also be helpful for us! We have a fully open-source app at https://transport.data.gouv.fr, and sometimes the internal APIs get gradually exposed on our SwaggerUI page (https://transport.data.gouv.fr/swaggerui), in which case we prefer to mark them explicitly as experimental/internal/unstable.

This issue is closed, I wonder if something else would fit the bill!

[crabvk]

With OpenAPI 3.0 I just add tag proposal to a path. Using Redocly it shows at the bottom of the summaries list as:

Screenshot

[andrezszambrano]

It is a shame they keep closing this issue.

[handrews]

@crabvk

It is a shame they keep closing this issue.

"They" don't "keep closing" this issue. The issue was closed six years ago by the person who filed it. Why do people keep commenting on closed issues? BTW, a proposal for an experimental has been accepted for consideration in a future version. There are also other open issues about lifecycles and versioning.

If you want to discuss a different feature, open a new discussion or issue. Don't comment on closed ones that we don't monitor, except to lock them when people won't stop commenting on them. Which doesn't mean no one wants to talk about it, it just means that we don't recycle old issues that were correctly closed many years ago.