Allow generation of servers and base paths in `api` about spot

[lfportal]

Given that spot is specifying the oas3 prefix, should there be any checks, of spot generates a specification below oas3? Or would specifying oas would be enough?

Spot supports conversion to the 2 major versions of OpenAPI specs (2 & 3). To reduce any false assumptions I think:

• oas* - can be understood by both v2 and v3
• oas2* - understood only by v2
• oas3* - understood only by v3

Does OAS need to specified internally for the variables oas3serverVariables?

I think keeping the prefix helps to communicate the intended usage for the annotation. It also allows Spot core annotations to reserve the unprefixed @serverVariables annotation for its own purposes.

If @default is missing, does the specification then not have a default value?

I would expect the Spot parser to complain about a missing @default and consider the contract invalid.

Alternatively we can also consider the following syntax:

@api({
  name: "My API",
  version: '1'
})
class Api {
  /**
   * The production API server
   */
  @oa3server({ url: "https://{username}.gigantic-server.com:{port}/{basePath}" })
  productionServer(
    /** this value is assigned by the service provider, in this example `gigantic-server.com` */ 
    @oa3serverVariable({ default: "demo" })
    username: String,
    @oa3serverVariable({ default: "8443" })
    port: "8443" | "443",
    @oa3serverVariable({ default: "v2" })
    basePath: String
  ) {}
}

or even:

@api({
  name: "My API",
  version: '1'
})
class Api {
  /**
   * The production API server
   */
  @oa3server({ url: "https://{username}.gigantic-server.com:{port}/{basePath}" })
  productionServer(
    /** this value is assigned by the service provider, in this example `gigantic-server.com` */ 
    @oa3serverVariable
    username: String = "demo",
    @oa3serverVariable
    port: "8443" | "443" = "8443",
    @oa3serverVariable
    basePath: String = "v2"
  ) {}
}

I'm not a huge fan of either though since we can't use the same strategy for types/schemas, whereas jsDoc @default tags can be easily used on any kind of Typescript element.

[lfportal]

@oben01 I might pick this up sometime next week, unless @mahirk has made a start on this?

[oben01]

Hello @mahirk @lfportal ,

To keep you posted I am working on this feature

[lfportal]

Server objects are OpenAPI 3 spec specific metadata. I'm thinking spec specific definitions should be prefixed for example @oa3server or @openapi3server rather than @server.

Using the following example from Server Object Example

{
  "servers": [
    {
      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",
      "description": "The production API server",
      "variables": {
        "username": {
          "default": "demo",
          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"
        },
        "port": {
          "enum": [
            "8443",
            "443"
          ],
          "default": "8443"
        },
        "basePath": {
          "default": "v2"
        }
      }
    }
  ]
}

What do you think of the following syntax?

@api({
  name: "My API",
  version: '1'
})
class Api {
  /**
   * The production API server
   */
  @oa3server({ url: "https://{username}.gigantic-server.com:{port}/{basePath}" })
  productionServer(
    @oa3serverVariables
    variables: {
      /**
       * this value is assigned by the service provider, in this example `gigantic-server.com`
       * 
       * @default "demo"
       */
      username: String,
      /**
       * @default "8443"
       */
      port: "8443" | "443",
      /**
       * @default "v2"
       */
      basePath: String
    }
  ) {}
}

• @oa3server can be declared multiple times to set multiple servers
  • url encapsulated as part of the annotation for consistency with the @endpoint annotation
• Standard @default jsDoc tag to specify default values rather than relying on any implicit value

Some other questions:

• Should variables allow anything but string types? e.g. port could be represented as Integer instead to convey intent
  • This would be converted back to string representations though when converted back to OpenAPI, so could seem like wasted effort for little gain

[mahirk]

I like that. I have a few questions, to understand the decorator usage primarily:

Given that spot is specifying the oas3 prefix, should there be any checks, of spot generates a specification below oas3? Or would specifying oas would be enough? Does OAS need to specified internally for the variables oa3serverVariables?

If @default is missing, does the specification then not have a default value?

Should variables allow anything but string types?

I think having everything as the string would be ideal in the longer term. I agree with your note there.

[mahirk]

Thank you! I'll work on this, unless someone else picks it up after completing the examples for the other parameters (#916 (comment)) and #1034

[oben01]

Hello,
Do we got any update ?