SPiD Tech Docs

Learn You a Docsite For Great Good

Agenda

  • Hows and whys
  • A guided tour
  • Contributing

Hows

  • An application, not a wiki
  • Gathers data, generates docs
  • Static site on AWS

Whys

  • Automation
  • Life cycle parity
  • Minimize doc rot
  • Speed

Downsides

  • Small changes are harder
  • More code to maintain
  • E-mails about broken builds from the docs

Tour

The tech docs site

Contributing

Data sources

  • The /endpoints endpoint
  • Sample responses from every endpoint
  • The Working Examples repos
  • Locally in the tech-docs repo

Editing Articles
and Guides

resources/articles/direct-payment-api.md

⬇

http://techdocs.spid.no/direct-payment-api/

Articles are written in markdown. 

  ## Heading

  Bacon ipsum dolor sit amet t-bone strip steak spare ribs bresaola, shank
  flank ground round filet mignon leberkas tri-tip kevin capicola.

  ### Subheading

  - Ordered lists
  - look like this

⬇

They have a title, body and aside 

  :title Direct Payment API

  :body

  The main content of the article.

  :aside

  The sidebar contents.

⬇

You can include code blocks, and they'll get highlighted: 

  ```java
  public static void main (String[] args) {
    System.out.println("Fencing code blocks! Engarde!");
  }
  ```

⬇

You can also fetch code snippets from the
working examples repos: 

  <spid-example
     lang="clj"
     src="/sso/src/spid_clojure_sso_example/core.clj"
     title="Build login URL"/>

⬇

There's support for tabs: 

  # :tabs

  ## :tab Java

  Java code goes here

  ## :tab PHP

  PHP code goes here

  # :/tabs

⬇

There's support for sequence diagrams: 

  ```sequence-diagram
  Browser->Server: Request a page
  Note right of Server: Fetch page contents from cache
  Server->Browser: Respond with some HTML
  ```

⬇

Link to relevant endpoints: 

  :relevant-endpoints

  GET /status
  POST /user

⬇

Insert table of contents: 

  ## Table of Contents

⬇

Editing Working Examples

https://github.com/schibsted/?query=examples 

  <spid-example
      lang="java"
      src="/sso/src/main/java/no/spid/examples/LoginController.java"
      title="Build login URL"/>

Excerpt from LoginController.java:

Editing Endpoint pages

Editing routes-file


  ./import-endpoints.sh

Editing endpoints-files

tech-docs/resources/endpoints/ 

  :introduction

  Markdown goes here

Supports relevant features of articles:

  • Markdown
  • Code highlighting
  • Inline code from working examples
  • Tabs
  • Sequence diagrams

  :relevant-types order user

  :relevant-endpoints

  GET /status
  POST /user

⬇


  :introduction

  Get verification and availability status for an email address. Note
  that the email should be base64 encoded.

  :example-params

  email: am9obkBkb2UuY29t

Editing type definitions

resources/types/voucher.edn 

  {:id :voucher}
resources/types/voucher.edn 

  {:id :voucher
   :name "Voucher"}
resources/types/voucher.edn 

  {:id :voucher
   :name "Voucher"
   :description "Vouchers are mainly described by the ..."}
resources/types/voucher.edn 

  {:id :voucher
   :name "Voucher"
   :description "Vouchers are mainly described by the ..."
   :fields []}
resources/types/voucher.edn 

  {:id :voucher
   :name "Voucher"
   :description "Vouchers are mainly described by the ..."
   :fields [{:name "voucherId"}]}
resources/types/voucher.edn 

  {:id :voucher
   :name "Voucher"
   :description "Vouchers are mainly described by the ..."
   :fields [{:name "voucherId"
             :type :integer-string}]}
resources/types/voucher.edn 

  {:id :voucher
   :name "Voucher"
   :description "Vouchers are mainly described by the ..."
   :fields [{:name "voucherId"
             :type :integer-string
             :description "Unique ID of the voucher ..."}]}
resources/types/voucher.edn 

  {:id :voucher
   :name "Voucher"
   :description "Vouchers are mainly described by the ..."
   :fields [{:name "voucherId"
             :type :integer-string
             :description "Unique ID of the voucher ..."
             :always-available? true}]}
resources/types/voucher.edn 

  {:id :voucher
   :name "Voucher"
   :description "Vouchers are mainly described by the ..."
   :fields [{:name "voucherId"
             :type :integer-string
             :description "Unique ID of the voucher ..."
             :always-available? true}]
   :inline-types [:voucher-status]}
resources/types/voucher-status.edn 

  {:id :voucher-status
   :name "Voucher status"}
resources/types/voucher-status.edn 

  {:id :voucher-status
   :name "Voucher status"
   :values []}
resources/types/voucher-status.edn 

  {:id :voucher-status
   :name "Voucher status"
   :values [{:value "-1" :description "Voucher is expired and can no longer be redeemed"}]}
resources/types/voucher-status.edn 

  {:id :voucher-status
   :name "Voucher status"
   :values [{:value "-1" :description "Voucher is expired and can no longer be redeemed"}
            {:value "0" :description "Voucher is generated and may be either used or handed out"}
            {:value "1" :description "Voucher is handed out. If the userId field is set, only this user may redeem it"}
            {:value "2" :description "Voucher is redeemed and can no longer be used. Kept only for historic reasons"}]}

Editing sample responses

Well, don't

Generating sample responses


  (defsample GET "/status")



  > rm generated/sample-response-cache/status-get.edn
  > rm generated/sample-responses/status-get.*



  > lein generate-sample-responses



  (defsample GET "/describe/{object}" {:object "User"})



  (defsample GET "/email/{email}/status"
    {:email (base64-encode "john@doe.com")})



  (defsample johndoe
    POST "/user" {:email "john@doe.com"
                  :displayName "John Doe"
                  :name "John Doe"})



  (defsample dataobject [user johndoe]
    POST "/user/{id}/dataobject/{key}" {:id (:userId user)
                                        :key "mysetting"
                                        :value "My custom value"})

Editing the front page

  • resources/frontpage.html
  • <list-of-articles/> 
    
  :title My article
  :frontpage
  • <apis-by-category/>
  • resources/endpoint-blacklist.edn

Adding an Endpoint

  • Look at the other endpoints in the routes-file
  • Add the new one, and have it deployed to staging
  • ./import-endpoints.sh

./import-endpoints.sh has your back

resources/types/kpi.edn

resources/endpoints/kpis-get.md

Want to know more?



Contributing to the tech-docs source code

Fin.