| 1 | ## About swagger
|
| 2 |
|
| 3 | * [What is Swagger?](#whatisswagger)
|
| 4 | * [How does the swagger module use Swagger?](#howdoes)
|
| 5 | * [Help me with YAML](#helpwith)
|
| 6 | * [Next step](#nextstep)
|
| 7 |
|
| 8 |
|
| 9 | ### <a name="whatisswagger"></a>What is Swagger?
|
| 10 |
|
| 11 | [Swagger™ ](http://swagger.io) is a specification and framework implementation for describing, producing, consuming, and visualizing RESTful web services.
|
| 12 |
|
| 13 | To read more about Swagger, refer to:
|
| 14 |
|
| 15 | * [The Swagger website](http://swagger.io)
|
| 16 | * [Swagger on GitHub](https://github.com/swagger-api)
|
| 17 |
|
| 18 |
|
| 19 | ### <a name="howdoes"></a>How does the swagger module use Swagger?
|
| 20 |
|
| 21 | The Swagger Editor lets you design your API specification and preview its documentation for your swagger API. The editor is installed with swagger.
|
| 22 |
|
| 23 | A swagger.yaml file is installed into every new swagger project, and lives in `<project_root>/api/swagger/swagger.yaml`. It conforms to the [Swagger 2.0 specification](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md).
|
| 24 |
|
| 25 | Behind the scenes, Swagger middleware validates and processes the Swagger configuration file, and routes API operation endpoints to controller files. All **you** need to do is implement your custom API controller logic.
|
| 26 |
|
| 27 | >Note: The editor is served locally and automatically saves your work *as you edit*. In addition, if the project is running (`swagger project start`), it is automatically restarted each time the editor saves. Just be careful if you kill the editor, that you do not lose unsaved work.
|
| 28 |
|
| 29 | **Try it:**
|
| 30 |
|
| 31 | 1. `swagger project create test-project`
|
| 32 | 2. `cd test-project`
|
| 33 | 2. `swagger project edit`
|
| 34 |
|
| 35 | *The Swagger editor*
|
| 36 | 
|
| 37 |
|
| 38 |
|
| 39 | ### <a name="helpwith"></a><a name="yaml"></a>Help me with YAML
|
| 40 |
|
| 41 | YAML is a data serialization/representation standard. If you're new to YAML, check out [www.yaml.org](http://www.yaml.org). Another excellent introduction is the [Wikipedia YAML entry](http://en.wikipedia.org/wiki/YAML).
|
| 42 |
|
| 43 | YAML is intended to be easy for humans to read. Every swagger project includes a Swagger 2.0 compliant configuration file that is written in YAML.
|
| 44 |
|
| 45 | ### <a name="nextstep"></a>Next step
|
| 46 |
|
| 47 | For a more detailed look the Swagger configurations, see "[The Swagger specification file](./swagger-file.md)".
|