Merge branch 'master' of github.com:tylerdave/OpenAPI-Tutorial

Author: Ian Zelikman

PREREQUISITES.md

@@ -5,8 +5,8 @@ In order to follow-along with the exercises in this tutorial you will need
 to install some applications and tooling. Installation can take a while so
 please try to make sure everything is installed before the session.
 
-Option 1: Vagrant + VirtualBox
-------------------------------
+Option 1: Vagrant + VirtualBox (recommended)
+-------------------------------------------
 
 We have created a VM with all of the required applications already installed
 and configured. To use it you will need to have Vagrant and Virtualbox
@@ -15,7 +15,9 @@ installed.
 - [Download & Install VirtualBox](https://www.virtualbox.org/wiki/Downloads)
 - [Download & Install Vagrant](https://www.vagrantup.com/docs/installation/)
 
-Once they're installed, clone this repo:
+*Be sure to reboot your host system after installing Vagrant + VirtualBox.*
+
+Once they're installed and you've rebooted, clone this repo:
 
 ```
 git clone https://github.com/tylerdave/OpenAPI-Tutorial.git
@@ -40,6 +42,9 @@ to localhost:2222 using an SSH clinet program. More details:
 - Connect via PuTTY: http://stackoverflow.com/a/9924122/
 - SSH with Git Bash: http://stackoverflow.com/a/16247703/
 
+### Using the VM
+
+See [VM.md](VM.md) for more usage information.
 
 Option 2: Manual Installation
 -----------------------------
@@ -87,7 +92,7 @@ python -m venv tutorial
 Install the implementation package and its dependencies:
 
 ```
-pip install -e tutorial-repo/implementation/betterapis
+pip install -e tutorial-repo/implementation
 ```
 
 Option 3: Backup Plan

README.md

@@ -5,16 +5,19 @@ Exercises and slides for our OSCON 2017 OpenAPI Tutorial:
 
 https://conferences.oreilly.com/oscon/oscon-tx/public/schedule/detail/56579
 
-Prerequisites
--------------
+Getting Started
+---------------
+
+To follow this tutorial you will need to have everything installed as 
+described in [PREREQUISITES.md](PREREQUISITES.md).
 
-To follow this tutorial, please make sure to install everything as described in
-[PREREQUISITES.md](PREREQUISITES.md).
+If you're using the recommended VM option, see [VM.md](VM.md) for more usage
+information.
 
 Repo Contents
 -------------
 
-- `lessons`: Tutorial lesson examples and solution files.
-- `implementation`: Example implementation using Connexions.
-- `presentation`: HTML presentation and source.
+- [lessons](lessons/): Tutorial lesson examples and solution files.
+- [implementation](implementation/): Example implementation using Connexions.
+- [presentation](presentation/): HTML presentation and source.
 

VM.md

@@ -0,0 +1,88 @@
+Using the VM
+============
+
+Once you have installed the VM following the instructions in 
+[PREREQUISITES.md](PREREQUISITES.md) (option 1) you are ready to begin using
+the tutorial tools!
+
+### Running the VM
+
+You can check the status of the VM by running `vagrant status` from within 
+the repo directory. If it is not already running, start it with
+`vagrant up --provider virtualbox`.
+
+### Logging In
+
+You can log in to the VM using `vagrant ssh` on the command line or by
+connecting to `localhost:2222` via ssh.
+
+VM Tools
+--------
+
+### Swagger Editor
+
+Two versions of the web-based [swagger-editor](https://github.com/swagger-api/swagger-editor)
+have been installed on the VM and should be accessible from the host machine. 
+
+http://localhost:8000/ - Swagger Editor 2.x (includes links to code generation service)
+
+http://localhost:8001/ - Swagger Editor 3.x (improved editor but no coge generation) 
+
+### Python API Implementation
+
+An example implementation using [Connexion](https://connexion.readthedocs.io/en/latest/)
+is included in the tutorial repo. To run it you first need to activate the
+Python virtual environment (using the `workon` command provided via
+virtualenvwrapper.):
+
+```
+workon tutorial
+```
+
+Then to run the connexion app:
+
+```
+python -m betterapis
+```
+
+With the application running, the API and Swagger UI are available from the 
+host machine.
+
+The API should be available here:
+
+http://localhost:8080/talks
+
+The Swagger UI for the API is available here:
+
+http://localhost:8080/ui/
+
+### Swagger Validator
+
+A validation tool has been installed. This will help you find errors in working
+specification files. For example, you can run it on one of the tutorial solution
+files:
+
+```
+swagger validate tutorial-repo/lessons/lesson-1.02/solution.yaml
+Results: 0 errors, 0 warnings
+```
+
+### Dredd
+
+The [Dredd](http://dredd.readthedocs.io/en/latest/) testing tool is installed.
+You may verify it works and see usage information by running:
+
+```
+dredd --help
+```
+
+### Swagger-codegen
+
+In addition to being available via links in the Swagger Editor 2.x,
+swagger-codegen is available on the command line in the VM. For usage
+information run:
+
+```
+java -jar swagger-codegen.jar help
+```
+