How to start using Swagger when it comes to defining APIs and more. Presentation from JavaCro17.

1. Miroslav Rešetar mresetar@croz.net
@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