Redoc: Add vendor extension support for API lifecycle annotations

[JSSAggie]

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

1. 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.