innoq/docster

transforming proxy that creates on the fly html documentation for your Json Rest api

Docster

Transforming proxy that creates an html represenation of your json hypermedia (e.g. HAL) api on the fly.

Running instances

• Docster instance on Heroku: https://docster-innoq.herokuapp.com
• Sample HAL API: https://lit-woodland-47740.herokuapp.com/

Start

SERVER_URI="my-server-base-uri" sbt run

or

sbt run -Dserver.uri="my-server-base-uri"

Execute tests

sbt test

Current Features

• transparent proxy
• HAL support:
  • displays relations
  • displays attributes
  • displays embedded entities

docster's Issues

add original response

set host header properly

fix compiler warnings

display rel documentation

Port numbers in curie links get lost

If the href value of a curie link contains a port number the description of the link relation contains the resolved link relation link but without port number, e.g., if the API returns the following HAL:

{
  "_links" : {
    "om:reports" : [ {
      "href" : "http://localhost:8020/reports",
      "templated" : false
    } ],
    "curies" : [ {
      "href" : "http://localhost:8020/rels/ordermanager/{rel}",
      "name" : "om",
      "templated" : true
    } ],
    ...

The link in description of om:reports will be http://localhost/rels/ordermanager/all.

docster should support multiple apis

possible concept:

1. GET / => docsters admin resource
2. here you can configure a new api domain under a unique string key. E.g. orders -> http://orders-manager
3. now you are able to transform all orders-manager endpoints by calling http://docster-domain/orders/*

The registered domains could be stored which would have the nice side effect of incrementally creating an api registry. Docster could automatically group the apis by Content-Type

should exchange the host in direct relation uris

or transform absolute to relative links

move to innoq heroku account

raise timeout thesholds

1 second is not enough

hal documentation response should include attributes section

add ITs for admin section

add syntax highlighting

hal documentation response should include headline

server uri should be configurable at runtime

hal documentation response should include actions section

create proper access log

pretty print json

support templated relations

transform absolute uris to relative ones in embedded entities

every relation should contain it's curie link

should keep response status code and headers when body is transformed

add heroku badge

hal documentation response should include relations section

add original request

combine proxyRequest and ProxyResponse values into one class

deploy to heroku

trailing slash in configured API URI leads to Bad Request

If the configured API URI ends with a slash, accessing the root resource leads to a

400 Bad Request 
'GET //' [Expected authority at index 2: //]

Without a trailing slash the same API URI works.

missing port part in description links

add some scala doc

missing description links for embedded entities

curies section in the root entity also applies for embedded resources: https://groups.google.com/forum/#!topic/hal-discuss/A-DNfNU2Nds

add navbar

hal documentation response should include embedded entities

add test for HAL embedded entities transformation

currently the test skeleton is ignored

proxy all incoming requests

done with 4be549f

transform HAL response into html representation

• only if client requested text/html
• only if server is not capable of serving text/html

create standalone mock

nested definition lists are not visible

bootstrapify

improve resource name detection strategy

currently the last path segment is used to detect the name of the entity, this is not working for

• collection entities
• home resources