Downloaded 115 times
![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)
Uploaded byTony Tam
API Design first with Swagger
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.
More Related Content
Similar to API Design first with Swagger
API Design first with Swagger
- 1. Putting API DesignFirst 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
- 3.
- 4.
- 5. Swagger Example Taken fromhttps://swaggerhub.com/api/fehguy/meetup-api/1.0.0 API Metadata
- 6. Swagger Example Taken fromhttps://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Host Metadata
- 7. Swagger Example Taken fromhttps://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Resources
- 8. Swagger Example Taken fromhttps://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Organizational Tags
- 9. Swagger Example Taken fromhttps://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Codegen Hints
- 10. Swagger Example Taken fromhttps://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Parameters
- 11. Swagger Example Taken fromhttps://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Expected Responses
- 12. Swagger Example Taken fromhttps://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Response Payload
- 13. Swagger Example Taken fromhttps://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Model Schemas
- 14. Swagger Example Taken fromhttps://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Required Properties
- 15. Swagger Example Taken fromhttps://swaggerhub.com/api/fehguy/meetup-api/1.0.0 Properties and Datatypes
- 16. How do youcreate 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 • CodeAnnotations, 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)
- 18.
- 19. Design First • Startwith 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
- 20.
- 21. Architecting for Maintainability Whoever thoughtof 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 itwork? • 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
- 25.
- 26. Setup • Add dependency •Enable as JaxRS Application
- 27. Setup • Create andconfigure inflector.yaml • Save a swagger specification
- 28. Run it! ... Nowwhat? • Definition parsed, loaded • Swagger definition mounted at basePath
- 29. Finding Controllers • Defaultlocation 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 • Methodname – 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 • MethodArguments – 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. Matchedby mapping in inflector.yaml 2. Extension on model 3. “Raw” JsonNode public ResponseContext addMeetup (RequestContext request, JsonNode meetup)
- 33. Hitting Endpoints • Noimplemented controller! Get mock data • Implement a controller… But it’s Wrong!
- 34. Hitting Endpoints • Responseschema declares array! Schema Validation!
- 35. Input Parameters • Designit the right way!
- 36. Putting Inflector inPractice • 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’sdone? What’s Missing?
- 38. Incremental Development • Movingto through SDLC
- 39. Extend it asneeded • Security? – Use the RequestContext! • Content Types? – Implement an EntityProcessor • Type Conversion? – Implement a Converter • Custom Input Validation? – Implement a Validator
- 40. Swagger Connected • Swaggeris FOSS • Specification + Tools at http://swagger.io • All source at https://github.com/swagger-api • Real-time support at irc.freenode.net #swagger
- 41.