The document provides an overview of Swagger, an open-source framework developed by SmartBear for designing, building, documenting, and consuming RESTful web services using the OpenAPI Specification (OAS). It discusses the benefits of using Swagger, such as standard documentation and auto-generated updates, as well as approaches for API documentation like API specification first and implementation first. Additionally, it highlights various Swagger annotations and credits contributors to the resources mentioned.

1. Swagger
Generating, visualizing and maintaining API docs

2. Agenda
● Introduction
● What is swagger
● Why swagger
● Documentation approaches
○ API specification first
○ Implementation first
2

3. ● Swagger is an open source software framework backed by
a large ecosystem of tools that helps developers
design, build, document and consume RESTful Web
services.
● Use OpenApi Specification (OAS)
● Developed by SmartBear Software.
● Apache License 2.0 licensed
● Released in 2011
3
Introduction

4. Swagger is...
TECHNOLOGY
A framework for :
● Producing
● Consuming
● Visualizing
REST-full APIs
METHODOLOGY
A specification for :
● Describing
● Documentaing
REST-full APIs
4

5. Why swagger
● Standard documentation
● Manage ad-hoc attributes
● Auto generated docs
● Up to date
These reasons are only for API doc, there are many more
things we can do with swagger
5

6. Place your screenshot here
Have a look...
That is how
swagger console
look, with our
API spec and
generated UI 6

7. Documentation approaches

8. API specification first
Write the
JSON spec
Generate
the API
stub
At last
define
APIs
8

9. OpenApi spec
Understanding OAS to
generate JSON spec of
our API
9

10. OAS objects
● Swagger
● Info
● Host
● BasePath
● Schemes
● Paths
● Definitions
● Tags
● externalDocs
10

11. Adding attributes in path object - query
11

12. Adding attributes in path object - path
12

13. Adding attributes in path object - formData
13

14. Adding attributes in path object - json body
14

15. Implementation first
Implement the
APIs
Put the
annotations
in place
15

16. Swagger- core Annotations
16
● @Api
● @ApiImplicitPara
m
● @ApiImplicitPara
ms
● @ApiOperation
● @ApiParam
● @ApiResponse
● @ApiResponses
● @ApiModel
● @ApiModelProper
ty

17. Swagger in lending mantra
Another approach : How we integrated
swagger in our application

18. Credits
Special thanks to all the people who made and released these
awesome resources for free:
● OpenApi spec
● Understanding $ref
● All about annotations
● Integrating Swagger-UI with Grails Application
● spring fox plugin documentation
18

19. Thanks!
Any questions?
You can find me at:
arif@fintechlabs.in
19