API Design first with Swagger
Download as PPTX, PDF8 likes2,856 views
The document discusses Swagger, a tool for API design that uses a structured format to describe APIs, facilitating consumer understanding and implementation. It outlines methods for creating Swagger specifications, such as code-first and design-first approaches, and introduces Swagger Inflector for managing API routing and generating mock data. The content emphasizes the importance of keeping documentation separate and maintaining a clean code environment while leveraging Swagger as the authoritative source for API definitions.
![Finding Controllers
• Default location from inflector.yaml
• Class name from Tag convention
– controllerPackage + tag[0].name
• Explicitly set as operation extension
– x-swagger-router-controller: org.your.Controller](https://image.slidesharecdn.com/tam-javaone-160921165058/85/API-Design-first-with-Swagger-29-320.jpg)
API Design first with Swagger
- 1. Putting API Design First with Swagger Tony Tam @fehguy
- 2. What is Swagger? • The basis of the Open API Specification – A Linux Foundation Project – https://openapis.org • A simple, structured way to describe your API • Methods, Resources, Parameters, media types • Everything your consumers need to know to consume your API
- 5. Swagger Example Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0 API Metadata
- 6. Swagger Example Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Host Metadata
- 7. Swagger Example Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Resources
- 8. Swagger Example Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Organizational Tags
- 9. Swagger Example Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Codegen Hints
- 10. Swagger Example Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Parameters
- 11. Swagger Example Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Expected Responses
- 12. Swagger Example Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Response Payload
- 13. Swagger Example Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Model Schemas
- 14. Swagger Example Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Required Properties
- 15. Swagger Example Taken from https://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Properties and Datatypes
- 16. How do you create a Swagger? • It’s just a JSON or YAML document! – Code First – Design First Code drives the Definition Definition drives the code
- 17. Code First • Code Annotations, comments for embedded documentation – Processed at compile-time, post-compile, runtime – Docs are always right! (code is the documentation) • Like Javadocs for REST APIs (but tons better)
- 19. Design First • Start with the Swagger Definition as a blueprint for the implementation – Code from the definition • Manual! Swagger Definition is just the implementation guideline • Automated with swagger-codegen
- 21. Architecting for Maintainability Whoever thought of this was an *#&&! Let’s go with a dramatic, 50 pitch roof
- 22. Removing the Cruft • Keep documentation outside your code • Don’t clutter up your code! – Use the Swagger Definition to drive your API, not just document it • You have a DSL, use it!
- 23. Introducing Swagger Inflector • Use Swagger as the Source of Truth for the API – Automatically route to controllers – Automatically map models – Generate Sample Data when controllers not implemented https://github.com/swagger-api/swagger-inflector
- 24. How does it work? • Inflector loads a Swagger Definition at startup • Parses routes, parameters, models • Uses configuration / extensions to find controllers by method signature – If a controller doesn’t exist, produces mock data • Routes requests to the Right Place • No Magic™ Software – Jersey 2.x – Jackson 2.x
- 26. Setup • Add dependency • Enable as JaxRS Application
- 27. Setup • Create and configure inflector.yaml • Save a swagger specification
- 28. Run it! ... Now what? • Definition parsed, loaded • Swagger definition mounted at basePath
- 29. Finding Controllers • Default location from inflector.yaml • Class name from Tag convention – controllerPackage + tag[0].name • Explicitly set as operation extension – x-swagger-router-controller: org.your.Controller
- 30. Finding Methods • Method name – Controller Class + explicit operationId • operationId: myMethod – Controller Class + generated operationId • operationId: clean(path) + httpMethod – Explicit extension • x-swagger-router-controller: org.your.Controller.methodName
- 31. Finding Methods • Method Arguments – Response class match • io.swagger.inflector.models.ResponseContext – Argument match • io.swagger.inflector.models.RequestContext • Arguments matching ordered operation parameters public ResponseContext getMeetups (RequestContext request, String title)
- 32. Complex Arguments 1. Matched by mapping in inflector.yaml 2. Extension on model 3. “Raw” JsonNode public ResponseContext addMeetup (RequestContext request, JsonNode meetup)
- 33. Hitting Endpoints • No implemented controller! Get mock data • Implement a controller… But it’s Wrong!
- 34. Hitting Endpoints • Response schema declares array! Schema Validation!
- 35. Input Parameters • Design it the right way!
- 36. Putting Inflector in Practice • Complete decoupling of API definition from business logic • Define API, concurrent development! Back-EndFront-End Auto-gen SDK Mock Data AdminController UsersController LoginController Incremental Impl!
- 37. Incremental Development • What’s done? What’s Missing?
- 38. Incremental Development • Moving to through SDLC
- 39. Extend it as needed • Security? – Use the RequestContext! • Content Types? – Implement an EntityProcessor • Type Conversion? – Implement a Converter • Custom Input Validation? – Implement a Validator
- 40. Swagger Connected • Swagger is FOSS • Specification + Tools at http://swagger.io • All source at https://github.com/swagger-api • Real-time support at irc.freenode.net #swagger
- 41. Thank you!