refactor: break down controller-spec

[jannyHou]

Description

related prototype PR: #916
related issue: #753
This PR is the 2nd of the 4 sub PRs I mentioned in #916 (comment)

When upgrade to OpenAPI 3, I break down the functions in openapi-v3/src/controller-spec.ts into 6 files, see folder.
This PR breaks down openapi0-v2/src/controller-spec.ts in a similar way, so we can compare the code change when upgrading them to v3 in the PR afterwards.

Checklist

• npm test passes on your machine
• New tests added or existing tests modified to cover all changes
• Code conforms with the style guide
• Related API Documentation was updated
• Affected artifact templates in packages/cli were updated
• Affected example projects in packages/example-* were updated

[jannyHou]

The namespace is called ControllerKeys, since they are used for processing controller class metadata.

The name of each key is changed from REST_* to * because the decorators are not tightly coupled with the rest package after being extracted to a single module.

And the values are renamed from rest:* to controller:*

I would like to hear more opinions on the names, thanks!

[shimks]

I like decoupling REST from the keys here. On top of that though, I think the keys should also have the word spec or something akin to it included as well since the metadata attached to those keys all are related to the specs.

[shimks]

I think organization-wise, controller-spec.ts should be renamed and broken into two or three pieces: operation decorators and others (@api and spec-building functions).

This is because I think the spec-building parts should live separately from the decorators assigning small pieces of spec metadata. Now as for @api I'm not sure whether that should live off separately from either of the other files. Thoughts?

Other than that, as long as TSLint didn't error out at unused imports or whatever, 👍

[shimks]

I like decoupling REST from the keys here. On top of that though, I think the keys should also have the word spec or something akin to it included as well since the metadata attached to those keys all are related to the specs.

[jannyHou]

@shimks

think organization-wise, controller-spec.ts should be renamed and broken into two or three pieces: operation decorators and others (@api and spec-building functions).

Now as for @api I'm not sure whether that should live off separately from either of the other files.

Good point! I agree to extract operation decorators to another file, and my personal take is split controller-spec.ts further into 3 pieces:

• @api
• operation decorators
• others, e.g. getControllerSpec and its subsequent functions

---

So let me summarize what will be in folder src/:

• json-to-schema.ts
  • generate Swagger schema for a model class according to its JSONDefinition
• keys.ts
  • keys to store/retrieve metadata
• parameter-decorator.ts
  • @param
• generate-schema.ts
  • generate body/non-body parameter's schema according to parameter type
• api-decorator.ts
  • @api
• operation-decorator.ts
  • @operation and its sugar functions
• controller-spec.ts
  • getControllerSpec and its subsequent functions

And

• index.ts exports
  • api-decorator.ts
  • controller-spec.ts
  • operation-decorator.ts
  • json-to-schema.ts
  • parameter-decorator.ts

[raymondfeng]

A controller can have metadata for different api styles. It's probably better to use openapi-v2 as the namespace. For example:

• openapi-v2:methods
• openapi-v2:parameters

Please note the controller is the target for such metadata, there is no need to add controller to the keys.

Later on, we can have more keys, such as:

• openapi-v3:methods
• openapi-v3:parameters
• grpc:methods
• grpc:parameters

[jannyHou]

Yeah a repeating of controller is too silly and could result in conflicts 🙊 I once named them as swagger:* while finally changed all to controller:* when thinking of we may add decorators of other classes like Response.
I am changing them back, the metadata target is already the best describe for its controller nature.

[jannyHou]

fixed in the last commit