In this session, Massimo will go through the Swagger specification and some open source tools built on top of Swagger. This includes Swagger editors and how they can be used to create our API stubs, the Swashbuckle tool to auto-generate swagger.json, to keep it in sync with the server code and to make it discoverable. Finally he will demonstrate the Swagger integration in the API Management space (Azure API Management and Sentinet).

1. Sponsored & Brought to you by
Everybody loves Swagger
Massimo Crippa
https://twitter.com/mas_que_crippa
https://be.linkedin.com/in/massimocrippa

2. Nice to meet you
Massimo Crippa
Integration Architect at Codit
 BizTalk D/I
 Api Management
massimo.crippa@codit.eu
codit.eu/blog
@mas_que_crippa
linkedin.com/in/massimocrippa

3. Agenda

4. Why APIs are trending
➔ Open Innovation and New
Markets. Enable firms to use internal as well as
external ideas and find new market paths
➔ Consume, Switch or Upgrade
Seamlessly. Drive both the API Consumer and
Provider towards a continuous improvement of quality
➔ Build on Partner Capabilities
➔ Increase Brand Presence
➔ Generate New Revenue Streams
➔ Enable Composite Enterprise
Approach where business functionalities become
small configurable blocks.
➔ Reduce time-to-market
➔ Fueled by mobile, cloud, big data
& IoT

5. The successful API
➔ Easy to consume (TTFSC, TTFHW)
➔ Understand the use, prevent the misuse (Data formats, authentication, error codes)
➔ Upgrade seamlessly
➔ Getting started, Multi language code samples, SDKs (DevEx)
The documentation is CRUCIAL

6. What is Swagger?
Edit the API specification in
YAML to produce the JSON
Editor
Layout, describe and
document your API
Specification
A dependency-free collection
of HTML / JS / CSS that
consumes the swagger.json
UI
Consume the swagger.json to
create client and server code
Code-Gen

7. The specification
Definition language to describe and document RESTful API
➔ Metadata
➔ info, basepath, consumes, produces, etc..
➔ Controllers (paths)
➔ Operations, HTTP verbs, status codes, schema refs
➔ Objects Definition (definitions)
➔ Parameters (e.g. skip)
➔ Responses
➔ Security (e.g. oauth)

8. The editors
API Specification-First
➔ Swagger Editor
➔ editor.swagger.io
➔ Editor + swagger.js
➔ apistudio.io
➔ Restlet studio (cross-format editor)
➔ studio.restlet.com

9. The Swagger UI
It’s a dependency-free collection of HTML / JavaScript / CSS
➔ List of APIs
➔ description, version, base path
➔ Drill-down to the operations
➔ http methods
➔ Description, Parameters, Types
➔ Try-out the API

10. Tools

11. Community-driven tools
Whole world of open source tools out there!

12. Swashbuckle
.NET library to auto-generate the swagger.json
➔ ApiExplorer to keep implementation and documentation in-sync
➔ Auto-generate as much as possible + extensibility points
➔ Discoverable (one endpoint per version)
➔ Minimal impact to your API
➔ Shashbuckle.core
➔ Shashbuckle
➔ Version 5.2.1
➔ vNext 6.0.0 beta7

13. Integrations

14. API Management

15. API Management
Azure API Management service
➔ Produces swagger 2.0
➔ Consumes 1.2 and 2.0
Sentinet by Nevatech
➔ Introduced with the version 4.6 (October 2015)
➔ Produces swagger 2.0
➔ Consumes 2.0

16. Takeaways
➔ A good developer experience is crucial to build a successful API
➔ Swagger is the de facto standard to describe modern APIs
➔ Swashbuckle: discoverable swagger.json + UI for devs
➔ Large number of applications and services that consume swagger

17. References
➔ Swagger
http://swagger.io/
➔ Swashbuckle
https://github.com/domaindrivendev/Swashbuckle/
➔ Microsoft Azure API Management
http://azure.microsoft.com/en-us/services/api-management/
➔ Sentinet by Nevatech
http://www.nevatech.com/

18. Thank you!