From f429764ca53a98123af0569daf749352b765d2dc Mon Sep 17 00:00:00 2001 From: Michael Mrowetz Date: Mon, 17 Apr 2017 15:11:06 +0900 Subject: [PATCH] misc tweaks to the docs --- docs/configuration.md | 2 +- docs/controllers.md | 12 +++++------- docs/mock-mode.md | 6 +++--- 3 files changed, 9 insertions(+), 11 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 4f50e430..fc804b22 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -2,7 +2,7 @@ ** NOTE: The following applies to swagger-node apps replying on swagger-node-runner 0.5.x and better. (ie. Any app using swagger-connect 0.1.0, swagger-express-mw 0.1.0, swagger-hapi 0.1.0, swagger-restify 0.1.0, or swagger-sails 0.1.0 - or higher versions of the same.) ** -Swagger-Node application configuration is driven by the file `default.yaml` (by default) in the application's config directory. Configuration is driven by the [config](https://github.com/lorenwest/node-config/wiki/Configuration-Files) module, so reference its documentation to understand how you may set up configuration per environment and perform configuration overrides. By default, the configuration file looks something like this: +Swagger-Node application configuration is driven by the file `default.yaml` (by default) in the application's `config` directory. Configuration is driven by the [config](https://github.com/lorenwest/node-config/wiki/Configuration-Files) module, so reference its documentation to understand how you may set up configuration per environment and perform configuration overrides. By default, the configuration file looks something like this: ```yaml # swagger configuration file diff --git a/docs/controllers.md b/docs/controllers.md index 7a94c463..552f7587 100644 --- a/docs/controllers.md +++ b/docs/controllers.md @@ -64,17 +64,15 @@ The Weather API requires a controller function that takes in request and respons Note that Open Weather returns a JSON object. Also, we'll need to export the controller function so that it is available to the outside world. -We will use the `request` library to make the request. So, add it to `package.json`: +We will use the `request` library to make the request. So, ensure it is installed and added to `package.json`: - ```javascript - "dependencies": { - "request": "" - }, + ``` +npm install request --save ``` ->Note: If a controller requires additional Node.js modules, be sure to add them to your package.json file and execute `npm install`. +>Note: If a controller requires additional Node.js modules, be sure to add them to your `package.json` file and execute `npm install`. -In the Swagger file, you can see that when a GET is performed on `/weather`, the target controller file is `api/controllers/weather.js`, and the target method to call is getWeatherByCity(): +In the Swagger file, you can see that when a GET is performed on `/weather`, the target controller file is `api/controllers/weather.js`, and the target method to call is `getWeatherByCity()`: ```yaml paths: diff --git a/docs/mock-mode.md b/docs/mock-mode.md index e467460f..42653edb 100644 --- a/docs/mock-mode.md +++ b/docs/mock-mode.md @@ -248,11 +248,11 @@ Here's an example that returns some data whenever the `search()` handler method } ``` -###Wiring up and implementing the API controller +### Wiring up and implementing the API controller After you're happy with your API design, you're ready to implement wire up the controller for the `/weather` path. -You simply specify in the OpenAPI spec the route handler (controller) file, which method to call in the controller (operationId), and any query parameters you wish to pass: +You simply specify in the OpenAPI spec the route handler (`x-swagger-router-controller`) file, which method to call in the controller (`operationId`), and any query parameters you wish to pass: In weather sample's `swagger.yaml` file, it looks like this: @@ -271,7 +271,7 @@ In weather sample's `swagger.yaml` file, it looks like this: type: "string" ``` -Finally, implement the route's operation -- the getWeatherByCity() method in `api/controllers/weather.js` -- which calls the back-end service and returns the response. +Finally, implement the route's operation -- the `getWeatherByCity()` method in `api/controllers/weather.js` -- which calls the back-end service and returns the response. Here is the sample controller implementation for a weather API: