RAML

Since the RAML project has decided to join the OpenAPI initiative and the RAML ecosystem lacks further development and additional tools, we decided to use and recommend using "OpenAPI specification (OAS)" as description standard instead.

RAML still provides advantages in modeling an API through it's more expressive modeling language and can produce OAS

RAML (the RESTful API Modelling Language) is a YAML-based API specification language. It's now available in version 1.0. The philosophy behind it is to specify the API before implementation.

If you follow this philosophy, you can design your API and discuss it with your clients and team before implementing a single line of code. API consumers are able to implement against the API before it's really up and running. The api-console provides a beautiful online documentation with "try it" features for your raml definition.

The RAML ecosystem provides a rich toolset for code generation (e.g. online editor; api-workbench), automatically generated documentation, code generation (e.g. go-raml), mocking, testing and much more. We prefer RAML over Swagger because of this.