feat: adds @tags convenience decorator

[mschnee]

Partially implements: #4300
See: #4406

This has been split from #4406 as a more manageable, smaller PR.

Added

This PR adds @oas.tags to Controller classes and methods, and adds an array of tag strings in accordance with the OpenAPI Operation Object specification.

As the spec defines tags as an optional property, this feature will only add tags: string[] when tags are set, and never an empty array of tags.

Using the @oas.tags decorator will set the tags on a path, and will be appended to any @tags set on a class.

This decorator is added to the oas namespace export in order to prevent naming conflicts with other popular decorators. The existing decorators in @loopback/openapi-v3 have also been added to the oas namespace (but not removed from the main export).

Not supported

This PR has no bearing on the top-level tags entity in the OpeAPI Tag Object specification. Operation Tags in the spec are themselves convenience for easily grouping and sorting paths and operations, and don't require an entry in the top level.

Examples

@oas.tags('Foo', 'Bar')
class MyController {
  @oas.tags('Baz')
  @oas.get('/greet')
  public async greet() {
    // tags will be [Foo, Bar, Baz]
  }
}

Checklist

• npm test passes on your machine
• New tests added or existing tests modified to cover all changes
• Code conforms with the style guide
• API Documentation in code was updated
• Documentation in /docs/site was updated
• (n/a) Affected artifact templates in packages/cli were updated
• Affected example projects in examples/* were updated

[raymondfeng]

I wonder if we should expose such decorators under a namespace (for example, @oas.tags) to avoid confusion against @bind({tags: ...}.

[mschnee]

That's a question I don't myself have an opinion on as a developer. I do know that sometimes, vscode intellisense will auto-import in a way I wasn't expecting: for example, typing @get might cause it to import { get } from 'http';,

But at the same time, I could import as instead:

import * as oas from '@loopback/openapi-v3';
@oas.api({})
@oas.deprecated()
class MyController {
    @oas.get('/greet')
    public async greet() {}
}

My only opinion as a developer is to be able to use some convenience decorators so that I don't have to write and maintain such verbose json blocks.

[raymondfeng]

@bajtos Please review.

[emonddr]

1. I agree with @raymondfeng about : @oas.tag
2. Wondering why todo controller from examples is being changed.

[mschnee]

☝️ I am attempting to resolve build issues after the most recent rebase.

[raymondfeng]

@op -> @operation?

[raymondfeng]

Maybe ## Shortcuts for OpenAPI Spec (OAS) Objects?

[dougal83]

Thinking about OAS enhancers, would it be a good/practical idea to add an optional description for each tag that would populate a sibling extension property? This information can be used (and cleaned up) by enhancer that would populate spec.tags. Draft tag enhancer.

  "tags": [
    "PingController"
  ],
  "x-tags": [
    {"description": "Api Ping response" }
  ],

[raymondfeng]

@mschnee Please address my last two comments so that we can land this PR soon.

[raymondfeng]

@dougal83 Please note there is a top level tags as an array of TagObject. The operation level tags is string[] containing references to top-level tags by name.

[mschnee]

Busy week, sorry for the delay! I am making the requested updated now.

@dougal83 I love the idea in general- the OAS spec has a top level tags block that allows for more extensive description. You sen peruse the spec documents here. It's not required to reference a tag in the operation spec, though. They can be the same, but the strings in a path tags are completely arbitrary.

For the first iteration of these convenience decorators, I'm trying to limit the scope to the direct developer experience of writing controllers.

You could probably do this now by creating your own top-level tags object, and referencing it:

// in tags file
export const myTags {
   Foo: {
      name: 'foo',
      description: 'foo tag'
   },
  Bar: {
    name: 'bar',
    description: 'bar tag'
  }
}

export const oasTags = Object.values(myTags); // use this in your api spec

// in controller
import { myTags } from '../../wherever'

@oas.tags(myTags.Foo.name, myTags.Bar.name)
class MyController {}

[mschnee]

Documentation updated.

Thanks for your patience and quick response @raymondfeng ! I'm going to take all of your feedback here and apply it to my PRs for the @deprecated and @response decorators.

[raymondfeng]

@mschnee PR landed. Great contribution! 🥇