API Documentation: Evaluation

This repository contains different libraries to convert from/to OpenAPI and RAML.

See READMEs in the different subfolders.

The used API spec resides in api-definition.

ToDo

Argus

openapi3

Ideas

• Convert from
  • OpenAPI ➡️ TypeScript/Scala
  • Scala ➡️ OpenAPI ➡️ TypeScript
  • Custom DSL ➡️ TypeScript/Scala

Notes

• JSON Schema

  • It is important to note that the schemas listed in an allOf, anyOf or oneOf array know nothing of one another. While it might be surprising, allOf can not be used to “extend” a schema to add more details to it in the sense of object-oriented inheritance.

    • Source: https://json-schema.org/understanding-json-schema/reference/combining.html#allof
    • ... but is used throughout libraries as extensions
    • ... and https://swagger.io/docs/specification/data-models/inheritance-and-polymorphism/