Documenting a REST API

I have found that MkDocs is pretty good. I can integrate it into a CICD build with little effort. What was not obvious was best practices for writing API docs. So I create a template! Check it out:

Tickers V1

---

Gives the user access to the available tickers.

Path: /rest/v1/tickers

GET /tickers/ticker/{ticker}

@PreAuthorize("hasAuthority('api')")
@RequestMapping(path = "/ticker/{ticker}",
    method = RequestMethod.GET,
    produces = MediaType.APPLICATION_JSON_VALUE )

Params

Param	Type	Required	Notes
ticker	path	YES

Info

Attribute	Value	Notes
hasAuthority	api	Must be an api user to make calls.
jwt	Bearer	Call must have valid bearer token.
consumes	NONE
produces	application/json	Generates JSON response.

curl example

curl -X GET -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0NjUxNzQyNDMsImF1dGhvcml0aWVzIjpbImFwaSJdLCJzdWJqZWN0IjoiMTE0OTEwOTg2ODIzOTczNDcwMTE0QGdvb2dsZSIsImlhdCI6MTQ2NTE3MDY0M30._cTZ_8rp0Z19cvzAGhXsNqD879KL9rAp17TWI3Qs6mk" 
-H "Cache-Control: no-cache" "https://api.dronze.com/rest/v1/tickers/ticker/AAPL"

response

{
  "id": "569f2d8b67d02fd037e5cd5e",
  "type": "ticker",
  "labels": [
    "AAPL",
    "APPLE INC"
  ],
  "embedded": {
    "currency": "USD",
    "cusip": "037833100",
    "exchange": "NASDAQ",
    "industry": "Electronic Equipment",
    "isin": "US0378331005",
    "last_updated": "Sep 25, 2015 12:00:00 AM",
    "perma_ticker_id": 199059,
    "prior_tickers": "None",
    "related_tickers": "None",
    "sic": 3571,
    "ticker": "AAPL",
    "ticker_name": "APPLE INC",
    "ticker_sector": "Technology"
  }
}

view raw example_rest.md hosted with ❤ by GitHub