dod-api-meetup-03262015-swagger-docs
Download as PPTX, PDF•0 likes•501 views
The document discusses the importance of Swagger as a tool for creating interactive documentation for RESTful APIs, highlighting its open-source nature and ease of use. It emphasizes how Swagger enables better understanding and interaction with APIs without the need for extensive implementation logic. Additionally, it mentions the Swagger UI as a collection of assets for generating visual documentation and the flexibility to customize it.
dod-api-meetup-03262015-swagger-docs
- 1. API Docs = A way for your technical and functional community to know what you have what they’re going to get and how to get it @jobrieniii – DoD API Meetup – 03/26/2015
- 3. We need more swagger… Awesome APIs with Shitty Docs = Useless APIs * * REST APIs
- 4. Static --- Difficult to maintain --- Eye glazing Dynamic and interactive --- Can be maintained as part of development process --- More fun
- 6. Swagger is a simple yet powerful representation of your RESTful API Interactive documentation, client SDK generation and discoverability 100% open source API tooling and developer support Source: http://swagger.io/
- 7. More buzzword bullets… • A standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. • Consumers can understand and interact with the remote service with a minimal amount of implementation logic. • Removes the guesswork in calling the service • Swagger-enabled APIs expose JSON files – These files can either be produced and served statically, or be generated dynamically from your application. • Swagger does not require you to rewrite your existing API • It does not require binding any software to a service--the service being described may not even be yours Source: https://github.com/swagger-api/swagger-spec
- 8. swagger-ui A dependency-free collection of HTML, Javascript, and CSS assets that dynamically generate beautiful documentation from a Swagger- compliant API. The Swagger project allows you to produce, visualize and consume your OWN RESTful services. No proxy or 3rd party services required. Do it your own way swagger json file(s) Describes your API resources Machine readable 2.0 is current spec https://github.com/swagger-api/swagger-spec { }
- 9. How do you create the Swagger JSON definition files?{ } manually editor.swagger.io (uses YAML) SDKs (include in your development / release process)
- 10. What if I don’t like the UI? Change it… it’s just some html/css/javascript
- 12. Quick Demo