tithonium/landscapist

An API description language that I don't hate.

LandscAPIst

Landscapist is an API definition tool.

Why?

Because I hate writing Swagger, but it's a 'widely supported standard', and none of the other options are any better. So I decided to write my own ruby DSL for defining my APIs, with tools to generate Swagger.

Usage

Generate a swagger document

bundle exec ./exe/landscapist swagger ~/workspace/myapp/doc/apis/apis.rb

Generate typescript interfaces

bundle exec ./exe/landscapist typescript ~/workspace/myapp/doc/apis/apis.rb

Run a webserver with Swagger-UI

bundle exec ./exe/landscapist server ~/workspace/myapp/doc/apis/apis.rb

landscapist's Issues

Global response codes

Be able to define application-level 500 response output, for example.

Connect documentation to unit tests

It would be really neat if there were some functionality to point from the documentation to the unit test(s) for that specific part of whatever API is being described. That way, when you are reading through the documentation, you can at a glance see where to look for unit tests, and potentially even vice versa; the unit tests could point back to some token in the documentation. It would also help tremendously in development, so that you don't have to keep separate lists of what pieces of an API you've already covered with unit tests and what work still needs to be done, since most code coverage tools can only tell if the API is being hit at all, not necessarily which parameters thereof have been tested, and so forth.

Support for TypeScript generics

TypeScript Documentation

Definition

interface Paginated<T> {
  pagination: {
    count: number
    limit: number
    offset: number
    total: number
  },
  records: T[]
}

Implementation

type contactsDirectory = Paginated<api.v1.contacts.Data>