For a written version of this presentation, see Implementing Swagger (OpenAPI specification) with your REST API documentation in my API doc course.
Image by Gulheim from The Noun Project
Swagger is a specification format for describing REST APIs. From this spec, you can create interactive documentation, automate test scripts, and more. Swagger is now called OpenAPI Specification.
The spec can be in either YAML or JSON formats.
paths: /pets: get: description: Returns all pets from the system that the user has access to operationId: findPets produces: - application/json - application/xml - text/xml - text/html parameters: - name: tags in: query description: tags to filter by required: false type: array items: type: string collectionFormat: csv - name: limit in: query description: maximum number of results to return required: false type: integer format: int32 responses: '200': description: pet response schema: type: array items: $ref: '#/definitions/pet'
For developers, it’s very easy to jump in the code and just change code. And once you change the code, you introduce backwards incompatibilities, you can break other features without realizing it. But the spec is still there, it says no, you have to test this, you have to make sure it stays consistent. It is the contract, and by following it you know you’re not breaking backwards compatibility.
— Michael Stowe (Podcast: Spec-driven Development of REST APIs, with a focus on RAML -- interview with Michael Stowe)
urlvalue to swagger spec.
See OpenAPI Specification on Github. The documentation takes some getting used to.
SwaggerHub provides Cloud-based Swagger hosting, with team access + more
RAML is a competing spec. Sample display: http://learnapidoc.com/raml/
Can I integrate Swagger into the rest of my docs? No, but see these resources: