README.md in rack-swagger-0.0.1 vs README.md in rack-swagger-0.0.6

@@ -18,14 +18,98 @@
 
     $ gem install rack-swagger
 
 ## Usage
 
-TODO: Write usage instructions here
+Set up a docs folder in your project. Place the root API doc there and call it
+"swagger.json". Place your resource API docs there as well. For example, if you
+have one resource called "pet", your docs folder will have two files:
 
+* swagger.json (the root API doc)
+* pet.json (the pet resource)
+
+In your config.ru, run Rack::Swagger.app(), passing in the path to your docs
+folder.
+
+```ruby
+run Rack::Swagger.app(File.expand_path("../docs/", __FILE__))
+```
+
+This will serve the swagger-ui front-end at **/docs/**, and your
+doc files at **/docs/api-docs/**. 
+
+Your resource definitions should look ike this:
+
+```json
+  {
+    "path": "/pet",
+    "description": "Operations about pets"
+  },
+```
+
+## Getting basePath right
+
+##### Using overwrite_base_path
+
+If you are seeing a lot of 404s or CORS-related errors in your docs, you may
+need to tweak the basePath.
+
+You always need to have the basePath point to the same hostname as your API. If
+you have multiple deploys of your application under different hostnames, and
+they share the same set of JSON files, you can use the overwrite_base_path
+option in Rack::Swagger.app() to vary this dynamically.
+
+For example, say you have an environment variable called MY_API_HOST, which
+contains the hostname of your app for a given deployment:
+
+```ruby
+  Rack::Swagger.app(
+    File.expand_path("../docs/", __FILE__),
+    overwrite_base_path: ENV["MY_API_HOST"]
+  )
+```
+
+##### Setting basePath manually
+
+If you're not using overwrite_base_path, rack-swagger will just use your
+basePath value from your JSON files. But just know that basePath will have
+different values depending on the file:
+
+* For the resource files, it should point to the API root path.
+* For the root file, it should point to the API root path, plus "/docs/api-docs".
+
+## Upgrading swagger-ui
+
+A distribution of swagger-ui is included with rack-swagger. For developers who
+want to upgrade this distribution, there is a Rake task which pulls down the
+latest version and applies some changes to it. To use, run:
+
+```
+rake swagger_ui
+```
+
+If someone downloads the distribution without using the Rake task and you're
+trying to restore back to the original, remove the directory and version
+file before running the rake task:
+
+```
+rm -rf swagger-ui/
+rm swagger_ui_version.yml
+rake swagger_ui
+```
+
+Then check in the updated code.
+
+## Notes
+
+For an example of properly formatted Swagger 1.2 JSON files working together
+with [swagger-ui](https://github.com/wordnik/swagger-ui), see:
+[http://petstore.swagger.wordnik.com/](Pet Store Demo).
+
 ## Contributing
 
 1. Fork it ( https://github.com/[my-github-username]/rack-swagger/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create a new Pull Request
+