Missing meta information

[hffmnn]

Is your feature request related to a problem? Please describe.

I am trying to convert an existing OpenApi file to spot. When trying to do that I am missing most of the meta-information parameters. For example:

• description for parameters and queries
• summary for the endpoint
• example for parameters and endpoints
• other content types than application/json e.g. application/xml for responses
• description for @interfaces

Describe the solution you'd like

Add these properties to the corresponding annotations (or in the case of annotations for interface types add new annotations.

Describe alternatives you've considered

Another option would be to add something like a global overwrite, that could add these properties (I guess by giving up the type-safety of TS).

As an example:

@api({
    name: "API",
})

@globalUnsafeOverrides({
  "openapi3": {
    "info": {
      "title": "Hello API"
    }
  }
})

would give this openapi3 doc:

{
  "openapi": "3.0.2",
  "info": {
    "title": "API",
    "version": "0.0.0"
  }

via sth. like that:

const finalJson = {
  ...api,
  ...globalUnsaveOverrides
}

Or the other way around (which would preserve the properties set in the annotated version)

const finalJson = {
  ...globalUnsaveOverrides,
  ...api
}

---

As an alternative for description for interface and its properties, I wonder if it is possible (and a good idea) to use e.g. surrounding comments.

// The user type
interface User {
  // the unique id
  id: string
}

would give

"components": {
    "schemas": {
      "User": {
        "type": "object",
        "description": "The user type",
        "properties": {
          "id": {
            "type": "string"
          },
         "description": "the unique id"
        },
        "required": [
          "id"
        ]
      }
    }
  }

EDIT: I found https://github.com/airtasker/spot/commit/aa517d3681bb8f6c3357390f3ff8933fcf6ee23c for the @endpoint annotation and wonder why it got removed?

[jimpudar]

Agreed, I'm definitely missing description, summary, and example!

[lfportal]

@hffmnn a bug was introduced as part of a migration that caused interface descriptions to not be parsed. This has been fixed in v1.0.2. Basic JsDoc descriptions are used to provide meta documentation. These are converted into description elements in OpenAPI. See Wiki - Documentation Syntax for details of how/what meta documentation is available.

As for the other features I'd suggest creating a separate tickets to track each of them:

Re: summary Currently there is no way to specify this. In sticking with JsDoc for meta documentation I'm thinking the following syntax could be introduced:

/**
 * My description
 *
 * @summary
 * My summary
 */
@endpoint({ method: "GET", path: "/path" })
MyEndpoint {
  // ...
}

Re: example Currently there is no way to document examples. Similar to summary we could introduce this as:

request(
  @pathParams
  pathParams:  {
     /**
      * An identifier
      *
      * @example <caption>Example 32</caption>
      * 32
      *
      * @example <caption>Example 64</caption>
      * 64
      */
     id: Int32
  }
  // ...
) {}

We should be able to parse these examples and check for type compatibility.

Re: other content types Spot is currently designed for purely JSON based APIs. A simple solution would be to just introduce an option to specify content type and always simply treat the body components as strings. However, it'd be better to introduce proper support for things like xml - complete with type checking etc.

[hffmnn]

Thanks a lot for the update. Will look into it tomorrow and see if I will open up other issues (as suggested)

[maxzirps]

I would like to try to add examples to the pathParams