(docs): Update or get rid of reserved-binding-keys.md

[shimks]

Came across reserved-binding-keys page in the docs and thought it needed to be updated to reflect the newest additions.

Another thought I had was that it was tedious for developers to update this page along with the more specialized docs they need to write.

My proposal is that this page be broken up and migrated into the appropriate pages. Alternatively, the page could be gotten rid of in favor of adding ts-docs in the source code to be generated into api-docs.

Details added as of March 12

• package: core

  • the following binding keys do not exist in core but in rest, according to the keys.ts (https://github.com/strongloop/loopback-next/blob/action-composition/packages/rest/src/keys.ts)
    • application.apiSpec
    • bindElement
    • getFromContext
  • components.${component.name} found in boot and repository, but not core
  • controllers.${controller.name} found in rest (?)

• package:rest

  • Under Rest Sequence Action Binding Keys, should the CONSTANT values of the following names be prefixed with SequenceActions? Looking from: https://github.com/strongloop/loopback-next/blob/master/packages/rest/src/keys.ts
    • sequence.actions.findRoute
    • sequence.actions.invokeMethod
    • sequence.actions.logError
    • sequence.actions.parseParams
    • sequence.actions.reject
    • sequence.actions.send

• package: openapi-spec

  • should be renamed to openapi-v3?
  • missing keys: https://github.com/strongloop/loopback-next/blob/master/packages/openapi-v3/src/keys.ts

• package: repository

  • Reserved prefixes > extra back-tick for `repositories.*``
  • cannot find the 3 binding keys in the code. Did I look at the wrong place or it no longer exist?

• the following packages do not exist in this page, not sure if this is as expected:

  • boot
  • build
  • cli
  • metadata
  • openapi-v3-types
  • repository-json-schema

• the page content should be in alphabetical order. Currently they are, except for rest.

Acceptance Criteria

• for keys.ts in each package, make sure it has ts annotation documenting the purpose of the key. It should contain information on binding key type and description.

  • authentication
  • boot
  • context
  • core
  • metadata
  • openapi-spec-builder
  • openapi-v3-types
  • openapi-v3
  • repository-json-schema
  • repository
  • rest

• Edit reserved-binding-keys.md so each package links to the appropriate section for it's reserved binding keys in apidocs.loopback.io.

• Update the Page describing the process for creating a new loopback-next package to include a step to update the reserved-binding-keys.md page with a link to the reserved keys for the new package.

Example

CoreBindings.APPLICATION_CONFIG

TYPE	DESCRIPTION
ApplicationConfig	Binding key for application configuration

[jannyHou]

the page could be gotten rid of in favor of adding ts-docs in the source code to be generated into api-docs.

I agree that we should auto generate the doc for them from code.

[dhmlau]

cross posting @jannyHou 's comment: (as i'm closing the other ticket)

openapi-spec is replaced by openapi-v3-types - it doesn't have binding keys
openapi-v2 is replaced by openapi-v3 - openapi-v3/keys

[dhmlau]

Marking this as Core-GA because this page contains outdated or missing information.

[dhmlau]

Based on the above discussion, there are 2 options:

Option 1:
remove this page and make sure apidoc contains the binding keys information (FYI - not all the keys.ts have all the relevant info)

Option 2:
keep this page, and update it

@strongloop/sq-lb-apex @bajtos @raymondfeng, any thoughts?

[virkt25]

Maybe each package should be responsible for listing it's Binding Keys instead of this page because that's the most intuitive place I would look for that information. Same applies for extensions, I would expect to look at the extension package's npm page / README for Usage Instructions and relevant binding keys. If we go with this approach, we can add a note in keys.ts to update the README if making changes to this file.

If not the README's, then I'm a +1 for automation into the apidocs pages.