Add vendor extension support for API lifecycle annotations

[JSSAggie]

trafficstars

We use redoc for our internal developer portal as well as our external public-facing developer portal. We have a need to display additional information about the lifecycle of an API. We could always add that information in the description but we want more. We want something more visible and called out. I am referring to calling them out as annotations.

There are a few ways we can go about this.

1. Add some sort of lifecycle definition and then each operation would define what lifecycles they want to use.

x-lifecycleAnnotationSetup:
  - name: Beta
    configuration:
      color: Red
      leftNav: true
  - name: In Development
    configuration:
      color: Blue
      leftNav: true
paths:
  /user:
    post:
      x-lifecycleAnnotations:
        - Beta

2. Each operation would define the lifecycle and the definition on each operation.

paths:
  /user:
    post:
      x-lifecycleAnnotations:
        - name: Beta
          configuration:
            color: Red
            leftNav: true

The result would be something like the image below. Ignore the mock as we were just hacking around to show an example:

I prefer option 1 but it does include two different vendor extensions. We would also like to build something that we can give back to the rest of the community. What are people's thoughts on this and how can we tailor it to meet a more general need?

My team will contribute to this effort but I want to make sure there is a desire to support this type of vendor extension in redoc.

[bburtin]

In a similar vein, I think it would be great to have a unified way to mark fields and endpoints as deprecated.

[cebe]

related issues on the OpenAPI specification:

• https://github.com/OAI/OpenAPI-Specification/issues/1973
• https://github.com/OAI/OpenAPI-Specification/issues/1616

[JSSAggie]

In a similar vein, I think it would be great to have a unified way to mark fields and endpoints as deprecated.

I know this is already supported as you can see here when an endpoint is deprecated. http://redocly.github.io/redoc/#operation/findPetsByTags

This is somewhat how I got my inspiration.

[bburtin]

Ha! I didn't realize that deprecation was already supported. Thanks for pointing it out.

[JSSAggie]

@RomanHotsiy Thoughts on this? We would like to get started as soon as we can.

[adamaltman]

I'm not sure about this one @JSSAggie -- it seems like we may want more of a lifecycle standard?

When I read the above, I wonder, why is this limited to lifecycle. What if I wanted other badges?

x-lifecycleAnnotationSetup --> x-badgeSetup x-lifecycleAnnotation --> x-badge

I feel like it's prescribing a use for some functionality which is not necessarily limited to that. If the x-lifecycleAnnotation was some kind of standard that was used by API gateways, etc... I think it would make more sense to leave it as it is.

Thoughts?

[RomanHotsiy]

@JSSAggie I find your proposal to be too narrow and too specific for redoc. I was considering closing this issue as out of scope.

But I agree with @adamaltman. It may work if we change it to something more generic like x-badge.

What do you think?

[JSSAggie]

@RomanHotsiy that was the reason for me posting here is because we want to build something that makes sense for everyone to benefit from.

@adamaltman I am totally on-board with the name change if we think it makes it more generic.

Do we think that having a setup section is needed or should we define all the badge information within each operation? I thought the setup solution will make it less verbose but not sure how open the team is to having more vendor extentions.

We could also not required the setup section and just use defaults if nothing is defined.

[richard-rance]

I like the global setup especially if you can define a description that appears when you hover over the badge.

For my use case, I want to define the lifecycle per operation, per parameter or per body property. In the case of the deprecated status I want to provide additional data such as the deprecation date and suggested migration path. That is more specific than I would expect ReDoc to provide but I'll put it out there.

[ziggythehamster]

I would like to +1 badge. There are some attributes and endpoints in our internal API docs which I would like to document as being something not ever intended to publicly document (e.g., identifiers which will never be useful because they are references used by systems we never intend on opening up, but we still want them in our internal docs).

The "Deprecated" badge, but with control over the color and text is all I actually need, and showExtensions: true would be good enough if I could style the resulting div+span+span. But they end up with randomized class names, so that doesn't work. Even having data-extension-key="x-audience" data-extension-value="company internal only" on the root div would do the trick, but it would be better obviously if the system supported a more standard way of displaying this info.

[mm-gmbd]

+1 for x-badge support. In need of a way to mark some endpoints in our documentation as "beta" and some as "experimental".

Having a badge be a combination of simply a text and color seems like it would cover things in a generic way. My requirement would be met by having the badge applied at the operation level.

Also, just thinking out loud -- I don't have a critical need for multiple badges for an operation, but would definitely be able to put that to use if an x-badge could be an array of badges. (also, what would happen if an x-badge was specified for an operation that was marked as deprecated? seems like multiple badges may need to be supported for that alone)

[mm-gmbd]

Created a draft PR for review if anyone is open: https://github.com/Redocly/redoc/pull/1947

Went with x-badges to support multiple badges -- screenshots show how it would be defined in the OpenAPI spec itself and how it's rendered on the operation.

Thoughts? (mentioning @RomanHotsiy directly as you seemed open to the idea of x-badge)

[mm-gmbd]

bump @RomanHotsiy or @adamaltman -- looking for input on the approach in this draft PR