Creation of OpenAPI spec from Directory TD

[farshidtz]

As raised in #77, we need to confirm if an equivalent OpenAPI spec can be generated from the directory TD.

It is possible that the OpenAPI Spec could even include additional information that is currently described in natural language outside of the TD.

Are there any tools to generate OpenAPI Specs from TDs?

[egekorkan]

It is very new but playground has support for this: https://github.com/thingweb/thingweb-playground/tree/master/playground-td_to_openAPI

This will be published as a separate package on npm and it will deployed on the browser version soon but it can be already used on its own

[wiresio]

I tried with @egekorkan 's playground editor. After manually correcting Query strings in paths are not allowed and Declared path parameter "id" needs to be defined as a path parameter at either the path or operation level I received the attached swagger document. Does that make sense?

discovery_yaml.txt

[wiresio]

FYI: a very nice visualization in swagger style appears when you load the TDD TD to: https://eclipse.github.io/editdor/

[wiresio]

I now manually added the events.
discovery_yaml.txt

[farshidtz]

I tried with @egekorkan 's playground editor. After manually correcting Query strings in paths are not allowed and Declared path parameter "id" needs to be defined as a path parameter at either the path or operation level I received the attached swagger document. Does that make sense?

discovery_yaml.txt

This looks promising. Apart from responses, most provided spec looks correct.

The request bodies of td write operations is defined as:

      requestBody:
        content:
          application/td+json: {}

The schema of these request bodies aren't defined in the directory's TD, so we can't blame the converter much. But content value given above is not a Map[string, Media Type Object]. I don't know if {} (empty YAML object in JSON notation?) is a valid Media Type Object. Swagger UI doesn't understand it as a schema object but it doesn't throw an error either. We should define the data schema in TD as object (i.e. "data": {"type": "object"}) to get something like:

      requestBody:
        content:
          application/ld+json:
            schema:
              type: object

[wiresio]

Thank you @farshidtz! Makes sense. Please find attached the adapted .yaml.
discovery_yaml.txt

One more thing: To avoid DELETE operations cannot have a requestBody, I commented the corresponding section (see e.g.: https://stackoverflow.com/questions/54939681/swagger-openapi-spec-3-0-delete-opeartion)

[farshidtz]

We also have a slightly outdated version here. Once updated, we can merge that with the converted spec and your additions to have a complete OpenAPI spec.

[mmccool]

Still a good idea, but from a practical sense we don't have time to do this any more in this cycle, so will defer.

[egekorkan]

I think it can be done informatively like the JSON Schema for the TD spec, even after the PR phase right?