diff --git a/PREREQUISITES.md b/PREREQUISITES.md index 1682ebb..d90f19b 100644 --- a/PREREQUISITES.md +++ b/PREREQUISITES.md @@ -5,11 +5,13 @@ 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. -**Clarification:** You may have seen instructions telling you have Node.js installed on your system. If you use Option 1, Node.js will be included on the -VM so you don't need it on your host system. +*If you prefer not to install all of the tooling individually you should use +Option 1. If you are comfortable with installing npm packages and setting +up a Python 3.4+ virtualenv then use Option 2 below.* -Option 1: Vagrant + VirtualBox (recommended) -------------------------------------------- + +Option 1: Vagrant + VirtualBox +------------------------------ 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 @@ -52,15 +54,11 @@ See [VM.md](VM.md) for more usage information. Option 2: Manual Installation ----------------------------- -*Only use this option if you're comfortable troubleshooting problems on your -own. We will not be able to offer much help with self-installed tools.* - If you prefer to install all the tools into your own development environment, you may install the following: ### Applications -- Java Runtime (7 or 8) - Node.js and npm - Python 3.4+ @@ -95,21 +93,26 @@ python -m venv tutorial source tutorial/bin/activate ``` -Install the implementation package and its dependencies: +With the `tutorial` virtualenv active, Install the implementation package and +its dependencies: ``` pip install -e implementation ``` -Option 3: Backup Plan ---------------------- +### Swagger / OpenAPI Editor + +If you used Option 1, a copy of the Swagger Editor is included in the VM. If +you chose Option 2 then you should either: + +- Use the online editor here: http://editor2.swagger.io/ +- Install it locally: https://github.com/swagger-api/swagger-editor/tree/2.x#running-locally -If you're unable to get everything installed correctly, you can still follow -most of the tutorial by using the online Swagger editor at -http://editor.swagger.io/#/ +*Note: For now we recommend using the 2.x version of the editor as the 3.x +version currently has some issues refreshing the validator.* -Recommended ------------ +Also Recommended +---------------- In order to test the API implementation locally, you should have a tool for making HTTP requests. You are free to use any tool you are comfortable with. We diff --git a/README.md b/README.md index c61be75..389d225 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,8 @@ OpenAPI-Tutorial ================ -Exercises and slides for our OSCON 2017 OpenAPI Tutorial: - -https://conferences.oreilly.com/oscon/oscon-tx/public/schedule/detail/56579 +Exercises and slides for our Tutorial: "Contract-First API Development Using +The OpenAPI Specification (fka Swagger)" Getting Started --------------- @@ -13,13 +12,13 @@ To follow this tutorial you will need: 1. A clone of this repo 2. Tools installed as described in [PREREQUISITES.md](PREREQUISITES.md). -If you're using the recommended VM option, see [VM.md](VM.md) for more usage +If you're using the VM option, see [VM.md](VM.md) for more usage information after you have everything installed. Having Trouble? --------------- -If you're having trouble getting set up for the tutorial, please email tylerdave@tylerdave.com with "OSCON Tutorial" in the subject. Please be sure to include your OS and a description of the problem including any error messages. +If you're having trouble getting set up for the tutorial, please email tylerdave@tylerdave.com with "OpenAPI Tutorial" in the subject. Please be sure to include your OS and a description of the problem including any error messages. Repo Contents ------------- diff --git a/presentation/slides.md b/presentation/slides.md index 0881426..f2c0e93 100644 --- a/presentation/slides.md +++ b/presentation/slides.md @@ -255,7 +255,7 @@ class: center, padded-top ??? - YAML stands for YAML aint markup language -- ~ It's a serializatin format +- ~ It's a serialization format - ~ meant to be more readable than JSON - ~ It's actually a superset of JSON and can be converted to JSON - ~ It has broad language support so it's starting to be used in a lot of places