Swagger - Making REST APIs friendlier
Download as PPTX, PDF•2 likes•1,034 views
This document discusses using Swagger to document REST APIs. It begins by providing an overview of Swagger and its capabilities. It then discusses OpenAPI as the de facto standard and how Swagger was donated to the OpenAPI Initiative. The document provides tips on getting started with Swagger and considerations for using JSON or YAML formats. It also discusses best practices like taking an "API-first" approach and examples of using Swagger in real projects. It covers potential issues like code generation and incorporating Swagger UI.
![Swagger UI – webjars
• Add dependency
• Copy index.html from swagger-ui webjar
• Change url and other customization features
19
compile("org.webjars:swagger-ui:${orgWebjarsSwaggerUiVersion}")
compile("org.webjars:webjars-locator:${orgWebjarsWebjarsLocatorVersion}")
window.onload = function() {
// Build a system
const ui = SwaggerUIBundle({
url: "/v2/api-docs",
validatorUrl: null,
dom_id: '#swagger-ui',
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout"
})
window.ui = ui
}](https://image.slidesharecdn.com/swagger-makingrestapisfriendlier-170512142112/85/Swagger-Making-REST-APIs-friendlier-19-320.jpg)
Swagger - Making REST APIs friendlier
- 1. Miroslav Rešetar [email protected] @MiroslavResetar SWAGGER - MAKING REST APIS FRIENDLIER STORIES FROM THE TRENCHES
- 2. Swagger 101 • Message from the thin • “Swagger™ is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services” • Enables • Server – to implement APIs • Client – to connect to APIs • UI – to visualize APIs • Language agnostic • Human and machine readable • Mostly used for HTTP but supports others • Speaks JSON and XML (REST format) • Can be described using JSON or YAML file 2
- 3. De-facto REST API specification standard 3
- 4. End of API Spec Wars – Swagger won 4
- 5. OpenAPI - De jure specification • In 2015 Swagger is donated to OpenAPI Initiative under Linux Foundation • Members: 5
- 6. OpenAPI Specification v3.0.0 • Currently in use is Swagger 2.0 • That’s why recommended URL to retrieve Swagger spec. is /v2/api-docs • New version v3.0.0 is currently RC and should arrive in few months • Not backward compatible but lossless upgrade from 2.0 is possible • Better support for JSON Schema • Currently (oneOf, anyOf, not, nullable, deprecated, writeOnly is not supported) • 3.0 supports • links (HATEOS style) • Callbacks (Webhook) • Examples 6
- 7. Swagger 2 vs OpenAPI 3 7
- 8. How to start with Swagger? • Get to know Swagger definition. • I should read documentation? Seriously? Well no. • Start using Swagger Editor 1. Import example (in old editor there is Open Example option) 2. Start changing things 3. When stuck go to documentation 4. Continue with step 2 until satisfied 8
- 9. What about JSON vs YAML? Which to choose? • Favorite consultant answer: It DependsTM • To be more concrete, use YAML if • Dense format and readability is a priority • You’re comfortable with reading and writing YAML • Your tools support YAML • Use JSON if • Machine interoperability is a priority (JSON is supported basically everywhere) • You are more comfortable with JSON • Tools you will use have better support for JSON • eg. json-schema-validator 9
- 10. Take the API first route • Why not do the opposite? Code first and expose current implementation as API? • Has some benefits like • Don’t need to know specification (but annotations) • Tools generate documentation from code • But: • You’re in the wrong context! You are already coding not designing. • Hard to include others (non-coders) in design phase • API should be first class citizen and deserves proper attention like • Separate project – API design project • Is done before server mock or client implementation • Should have approval from consumer and provide • Consumer having greater weight in decision making 10
- 11. SpringFox – I bring annotation pollution • 33 lines of code • Only 9 is non-Swagger code • 27% computing code is just unacceptable 11
- 12. Swagger in Real Life – Example 1 • Problem: New development in banking sector, two teams needs to communicate • Swagger API first design approach • Collaboration via editing one file • Team members had to power to “ask for feature” by updating the specification • Tools used: • Swagger Editor • Online version, start from Petstore sample and strip down unnecessary • Specification format • YAML – because greater readability & less lines to write • Maven • swagger-codegen-maven-plugin to generate API Java Model objects 12
- 13. Swagger in Real Life – Example 1 13 api-model project Swagger YAML API swagger-codegen-maven- plugin generate Java model back-services project Nexus repository Jenkins Maven build front-services project Ext.JS UI API is build by Jenkins job and artifact (JAR) is published on Nexus repository Backends For Frontends pattern Single-purpose Edge Services for UI Proxies and adapts API for UI app API is implemented by Spring Boot app by using api-model as API model spec. Web application is end user of the API
- 14. Swagger in Real Life – Example 2 • Problem: System integration with complex business domain problem (telco) • Swagger API JSON schema first design approach • Collaboration via editing one file editing sample JSON files • Creating JSON Schemas from JSON examples • Using those JSON schemas as models for Swagger API • Tools used: • Text editors & JSON 2 schema helpers (https://jsonschema.net/#/editor) • Specification format • JSON – because JSON schema supports better JSON than YAML • Gradle • jsonschema2pojo-gradle-plugin – to generate API Java Model objects • swagger-codegen-plugin – to generate REST clients stubs (actually just models for know 14
- 15. Swagger in Real Life – Example 2 15 api-model project JSON Schema files Generated API Java models External system Swagger-UI exposes API and schemas Api-service and web projects Depends upon api-model project Implement business logic such as message validation upon JSON schema Uses api-model project for API client creation
- 16. Generators gotchas • Plugins available don’t offer flexibility expected • eg. swagger-codegen-plugin will put all model objects in the same package • You may need to agree date-time format which you will use • ISO 8601 is a start • Eg. It is hard to have model to generate both LocaleDateTime and OffsetDateTime (with timezone) or another place • You may not want to regenerate classes every time • eg. You need to edit them by hand 16
- 17. 17 Swagger specification Swagger-UI – one way to render spec.
- 18. Incorporating Swagger-UI into application • (More than) few options: 1. You don’t include it • You can use online available at http://petstore.swagger.io/ if your API is available online 2. If you use SpringFox add SpringFox UI dependency 3. You can use webjars to add dependency to swagger-ui 4. Build Docker container with swagger-ui and web server 5. Clone swagger-ui git repo (dist) and copy it to web application 18
- 19. Swagger UI – webjars • Add dependency • Copy index.html from swagger-ui webjar • Change url and other customization features 19 compile("org.webjars:swagger-ui:${orgWebjarsSwaggerUiVersion}") compile("org.webjars:webjars-locator:${orgWebjarsWebjarsLocatorVersion}") window.onload = function() { // Build a system const ui = SwaggerUIBundle({ url: "/v2/api-docs", validatorUrl: null, dom_id: '#swagger-ui', presets: [ SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset ], plugins: [ SwaggerUIBundle.plugins.DownloadUrl ], layout: "StandaloneLayout" }) window.ui = ui }
- 20. Swagger UI gotchas • If Swagger UI is not deployed together with application you need to implement CORS support to serve API spec • The base URL is defined by root level • schemes • host • basePath • Leave those empty if: • Your endpoints use the same scheme, host and basePath as Swagger spec location • This gets you functionality that “Try it out” works across environments • Swagger-UI will try to download referenced JSON schemas • You need to ensure that whole Swagger spec with referenced schemas can be downloadable 20
- 21. Q & A 21
Editor's Notes
- #4: Yesterday, MuleSoft, the creators of RAML, announced that they have joined the Open API Initiative. Created by SmartBear Software and based on the wildly popular Swagger Specification, the OpenAPI Initiative is a Linux Foundation project with over 20 members, including Adobe, IBM, Google, Microsoft, and Salesforce.
- #5: Yesterday, MuleSoft, the creators of RAML, announced that they have joined the Open API Initiative. Created by SmartBear Software and based on the wildly popular Swagger Specification, the OpenAPI Initiative is a Linux Foundation project with over 20 members, including Adobe, IBM, Google, Microsoft, and Salesforce.