discoverydoc 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d51024b7e141eee992dd64b1021008e3d12b267e
+  data.tar.gz: fb149b32b39e8d4ac1cd992d23b2775eaa96f799
+SHA512:
+  metadata.gz: 2746d3e1357bd86aa4aa40f82e704bdf12f2cc605e05402c6dff8df15354841fb19af19ef94fa4d5f93d57512bf34d27b466bd04db77252d7920f105e6c3d53a
+  data.tar.gz: f7fd8303ba768cad52a50afac01bdb7a2e2c6720dc22211af0a7531ba28ff708753fdbbbdc3c5a2e5b81de8010df50deea6dd3a5619c00d52e3702bf24d2a8cf

data/.gitignore

@@ -0,0 +1,2 @@
+.idea
+.gem

data/Gemfile

@@ -0,0 +1 @@
+gem "rspec"

data/Gemfile.lock

@@ -0,0 +1,21 @@
+GEM
+  specs:
+    diff-lcs (1.2.5)
+    rspec (3.1.0)
+      rspec-core (~> 3.1.0)
+      rspec-expectations (~> 3.1.0)
+      rspec-mocks (~> 3.1.0)
+    rspec-core (3.1.7)
+      rspec-support (~> 3.1.0)
+    rspec-expectations (3.1.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.1.0)
+    rspec-mocks (3.1.3)
+      rspec-support (~> 3.1.0)
+    rspec-support (3.1.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rspec

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 kaiinui
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -0,0 +1,103 @@
+discoverydoc
+============
+
+Generate markdown document from discovery file.
+
+From following YAML Dicovery file,
+
+```yaml
+service:
+  name: BookService
+  id: com.example.book_service
+  base_url: http://example.com/book_service/api
+
+endpoint:
+  ListBook:
+    path: GET /books
+    response: [Book]
+  GetBook:
+    path: GET /books/{id}
+    response: Book
+  PostBook:
+    path: POST /books
+    body: Book
+    response: Book
+  PatchBook:
+    path: PATCH /books/{id}
+    body: Book
+    response: Book
+  SearchBook:
+    path: GET /books/search
+    params:
+      query: String
+    response: [Book]
+
+entity:
+  Book:
+    title: String
+    author_name: String
+    published_at: Date
+
+error:
+  id: String
+  message: String
+  url: String
+```
+
+Following markdown documentation is generated.
+
+---
+
+## BookService Service 
+
+### Base URL 
+
+http://example.com/book_service/api
+
+## Endpoint
+
+### `GET /books` (ListBook) 
+
+#### Response 
+
+[Array(Book)](#book)
+
+### `GET /books/{id}` (GetBook) 
+
+#### Response 
+
+[Book](#book)
+
+### `POST /books` (PostBook) 
+
+#### Response 
+
+[Book](#book)
+
+### `PATCH /books/{id}` (PatchBook) 
+
+#### Response 
+
+[Book](#book)
+
+### `GET /books/search` (SearchBook) 
+
+#### Parameters 
+
+|Field|Type|
+|-----|----|
+|query|`String`|
+
+#### Response 
+
+[Array(Book)](#book)
+
+## Entity
+
+### Book 
+
+|Field|Type|
+|-----|----|
+|title|`String`|
+|author_name|`String`|
+|published_at|`Date`|

data/bin/discoverydoc

@@ -0,0 +1,7 @@
+#!/usr/bin/ruby
+
+require_relative '../lib/discovery_doc/discovery_doc'
+
+filepath = ARGV[0]
+builder = DiscoveryDoc::DocBuilder.new
+puts builder.from_file filepath

data/discoverydoc.gemspec

@@ -0,0 +1,14 @@
+Gem::Specification.new do |s|
+  s.name = 'discoverydoc'
+  s.version = '0.1.0'
+  s.summary = 'Generates Markdown documentation from YAML discovery file.'
+  s.author = 'Kai INUI'
+  s.email = 'lied.der.optik@gmail.com'
+  s.homepage = 'https://github.com/kaiinui/discoverydoc'
+  s.files = `git ls-files`.split("\n")
+  s.test_files = `git ls-files -- spec/*`.split("\n")
+  s.license  = 'MIT'
+  s.executables << 'discoverydoc'
+
+  s.add_development_dependency 'rspec'
+end

data/lib/discovery_doc/discovery_doc.rb

@@ -0,0 +1,159 @@
+require "yaml"
+
+module DiscoveryDoc
+  class DocBuilder
+    ## Returns Markdown document from a file that specified by given filepath.
+    ##
+    ## @param filepath [String] File path to a discovery file.
+    ## @return String
+    def from_file(filepath)
+      discovery = YAML.load_file(filepath)
+      parse(discovery)
+    end
+
+    ## Returns built Markdown document.
+    ##
+    ## @param discovery [Hash]
+    ## @return String
+    def parse(discovery)
+      doc = ""
+      doc << parse_service(discovery["service"])
+      doc << parse_endpoints(discovery["endpoint"])
+      doc << parse_entities(discovery["entity"])
+      doc
+    end
+
+    ## Working with Service
+
+    def parse_service(service)
+      name = service["name"]
+      base_url = service["base_url"]
+
+      doc = ""
+
+      doc << "## #{name} Service \n\n"
+
+      doc << "### Base URL \n\n"
+
+      doc << base_url
+
+      doc << "\n\n"
+
+      doc
+    end
+
+    ## Working with Entity
+
+    def parse_entities(entities)
+      doc = ""
+
+      doc << "## Entity\n\n"
+
+      entities.each do |name, entity|
+        doc << "### #{name} \n\n"
+
+        doc << table_from_field_type_hash(entity)
+      end
+
+      doc
+    end
+
+    ## Working with Endpoint
+
+    ## @param endpoints [Hash]
+    def parse_endpoints(endpoints)
+      doc = ""
+      doc << "## Endpoint\n\n"
+
+      endpoints.each do |name, endpoint|
+        doc << parse_endpoint(name, endpoint)
+      end
+
+      doc
+    end
+
+    ## @param name [String] Endpoint's name
+    ## @param endpoint [Hash]
+    ## @return String
+    def parse_endpoint(name, endpoint)
+      doc = ""
+      path = endpoint["path"]
+      parameters = endpoint["params"]
+      response = endpoint["response"]
+      content_type = endpoint["content_type"]
+
+      doc << "### `#{path}` (#{name}) \n\n"
+
+      if content_type
+        doc << "Content-Type: #{content_type}\n\n"
+      end
+      doc << parse_parameters(parameters)
+
+      doc << parse_response(response)
+
+      doc
+    end
+
+    ## @param parameters [Hash]
+    def parse_parameters(parameters)
+      return "" unless parameters
+
+      doc = ""
+      doc << "#### Parameters \n\n"
+
+      if parameters.is_a?(String) or parameters.is_a?(Array)
+        doc << link_to_entity(parameters)
+      elsif parameters.is_a?(Hash)
+        doc << table_from_field_type_hash(parameters)
+      end
+
+      doc
+    end
+
+    ## @param response [String|Hash|Array]
+    def parse_response(response)
+      doc = ""
+
+      doc << "#### Response \n\n"
+
+      if response.is_a?(String)
+        doc << "[#{response}](##{response.downcase})\n\n"
+      elsif response.is_a?(Array)
+        doc << "[Array<#{response[0]}>](##{response[0].downcase})\n\n"
+      else
+        doc << table_from_field_type_hash(response)
+      end
+
+      doc
+    end
+
+    ## Helpers (Working with Markdown)
+
+
+    ## @param entity [String|Array]
+    def link_to_entity(entity)
+      if entity.is_a?(String)
+        "[#{entity}](##{entity.downcase})"
+      elsif entity.is_a?(Array)
+        "[Array(#{entity[0]})](##{entity[0].downcase})"
+      end
+    end
+
+    ## Returns table markdown with Field to Type hash.
+    ##
+    ## @param field_type_hash [Hash]
+    ## @return String
+    def table_from_field_type_hash(field_type_hash)
+      doc = ""
+      doc << "|Field|Type|\n"
+      doc << "|-----|----|\n"
+      field_type_hash.each do |field, type|
+        type = "Array<#{type[0]}>" if type.is_a?(Array) ## For [Entity] literal.
+        doc << "|#{field}|`#{type}`|\n"
+      end
+      doc << "\n"
+
+      doc
+    end
+  end
+end

data/spec/discovery-1.0.0.yml

@@ -0,0 +1,100 @@
+service:
+  name: FilmAPI
+  id: net.filmapp.api
+  base_url: https://filmappapi.appspot.com
+
+endpoint:
+  ### Deltas API ###
+  GetDeltas:
+    path: GET /deltas
+    params:
+      ust: Integer
+      device_token: String
+    response: DeltaPack
+  PostDeltas:
+    path: POST /deltas
+    body: DeltaPack
+    response:
+      id: String
+      message: String
+
+  ### Photo Upload API ###
+  UploadPhoto:
+    path: POST /upload/photos/{gid}
+    content_type: multipart/form-data
+    params:
+      image: Image
+    response: PhotoUploadResponse
+
+  ### Entity API ###
+  GetPhoto:
+    path: GET /photos/{gid}
+    response: Photo
+  GetMultiplePhotos:
+    path: GET /photos/{comma_separated_gids}
+    response: [Photo]
+  GetAlbum:
+    path: GET /albums/{gid}
+    response: Album
+
+entity:
+  DeltaPack:
+    _id: String
+    _ust: Integer
+    Photo: [Photo]
+    Album: [Album]
+  Photo:
+    gid: Key
+    localIdentifier: String
+    assetURL: String
+    albumIdentifier: String
+    burstIdentifier: String
+    collectionIdentifier: String
+    mediaType: Integer
+    mediaSubType: Integer
+    pixelWidth: Integer
+    pixelHeight: Integer
+    duration: Integer
+    latitude: Double
+    longitude: Double
+    hasUploaded: Boolean
+    remoteImageURL: String
+    aq_gid: String
+    aq_deviceToken: String
+    aq_localTimestamp: Long
+    aq_idDeleted: Boolean
+    aq_ust: Long
+    creationTimestamp: Long
+    modificationTimestamp: Long
+  Album:
+    gid: Key
+    assetsGroupURL: String
+    localIdentifier: String
+    headerPhotoIdentifier: String
+    title: String
+    tintColorHex: String
+    backgroundColorHex: String
+    themeColorHex: String
+    layoutThemeIdentifier: String
+    themeIdentifier: String
+    aq_gid: String
+    aq_deviceToken: String
+    aq_localTimestamp: Long
+    aq_idDeleted: Boolean
+    aq_ust: Long
+    latestPhotoCreationTimestamp: Long
+    creationTimestamp: Long
+    modificationTimestamp: Long
+  User:
+    userToken: String
+    secretKey: String
+  Device:
+    deviceToken: String
+    secretKey: String
+  PhotoUploadResponse:
+    id: String
+    image_url: String
+
+error:
+  id: String
+  message: String

data/spec/sample-1.0.0.yml

@@ -0,0 +1,36 @@
+service:
+  name: BookService
+  id: com.example.book_service
+  base_url: http://example.com/book_service/api
+
+endpoint:
+  ListBook:
+    path: GET /books
+    response: [Book]
+  GetBook:
+    path: GET /books/{id}
+    response: Book
+  PostBook:
+    path: POST /books
+    body: Book
+    response: Book
+  PatchBook:
+    path: PATCH /books/{id}
+    body: Book
+    response: Book
+  SearchBook:
+    path: GET /books/search
+    params:
+      query: String
+    response: [Book]
+
+entity:
+  Book:
+    title: String
+    author_name: String
+    published_at: Date
+
+error:
+  id: String
+  message: String
+  url: String

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: discoverydoc
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kai INUI
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-12-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email: lied.der.optik@gmail.com
+executables:
+- discoverydoc
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- bin/discoverydoc
+- discoverydoc.gemspec
+- lib/discovery_doc/discovery_doc.rb
+- spec/discovery-1.0.0.yml
+- spec/sample-1.0.0.yml
+homepage: https://github.com/kaiinui/discoverydoc
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Generates Markdown documentation from YAML discovery file.
+test_files:
+- spec/discovery-1.0.0.yml
+- spec/sample-1.0.0.yml
+has_rdoc: