Swagger - Design and Document your REST APIs

•

6 gefällt mir•1,584 views

Introduction to Open API specification, a.k.a. Swagger specification. These are slides for my talk: https://www.youtube.com/watch?v=y-34F7FbfiM&t=1063s The talk includes a live demonstration on writing a Swagger specification and short Q&A segment. Enjoy! This talk was hosted by the API Craft Singapore Meetup group (https://www.meetup.com/API-Craft-Singapore/) in December 2016.

Software

Tai Shi Ling
Full Stack Web App Developer
Co-founder, Uilicious

I used to document them on wiki like this:

But I find myself spending more time on
formatting then writing the docs.

But… how do I tell people the schema for the request?

Open API Specification
aka SWAGGER Specification
Framework for describing APIs
for the discovery of APIs
by humans and machines

Open API Specification
aka SWAGGER Specification
Like WSDL is for SOAP APIs.

How can I prototype my APIs?
How can I validate my APIs?
How can I keep my specs and documentation in sync?
How can I share my API specs?

Swagger specs look like this:
YAML or JSON
It’s easy to learn!

Design Swagger Editor
Build Swagger CodeGen
Document Swagger UI
Core Tools

Design | Swagger Editor
Code completion
Error checking
Preview & test APIs

Build | Swagger CodeGen
Generate server stub code (>20 languages)
Generate client SDKs (>40 languages)

Document | Swagger UI
API explorer
Plug in a url to any
swagger doc to
explore its APIs

Design | Swagger Editor
1. No Installation: editor.swagger.io

2. Docker:
docker pull swaggerapi/swagger-editor
docker run -p 80:8080 swaggerapi/swagger-editor
Design | Swagger Editor

3. NodeJS:
git clone https://github.com/swagger-api/swagger-editor.git
cd swagger-editor
npm install
npm start
Design | Swagger Editor

Wait, there’s more!
http://swagger.io/specification/

Design | Swagger Editor
Things to note…
Getting around CORs:
https://github.com/swagger-api/swagger-editor/blob/master/docs/cors.md
Study at your leisure.

Document | Swagger UI
1. Clone or download Swagger UI:
https://github.com/swagger-api/swagger-ui
2. Open ./dist/index.html in your fav text editor
3. Change the default url to your swagger ﬁle location
4. Open ./dist/index.html in your browser

Document | ReDoc
https://github.com/Rebilly/ReDoc

Document | ReDoc
<!DOCTYPE html>
<html>
<head>
<title>ReDoc</title>
<!-- needed for adaptive design -->
<meta name="viewport" content="width=device-width, initial-scale=1">
<!--
ReDoc doesn't change outer page styles
-->
<style>
body {
margin: 0;
padding: 0;
}
</style>
</head>
<body>
<redoc spec-url='http://petstore.swagger.io/v2/swagger.json'></redoc>
<script src="https://rebilly.github.io/ReDoc/releases/latest/redoc.min.js"> </script>
</body>
</html>
All you need is:

I hope my docs look like this in the future:

What about alternatives?
RESTful API Modeling Language
- YAML syntax
- Hierarchical schema

What about alternatives?
- Markdown Syntax
- Hierarchical schema

Why Swagger?
Flat schema is more readable. :)

Some nice resources
Tutorial:
http://idratherbewriting.com/pubapis_swagger/

Weitere ähnliche Inhalte

Andere mochten auch

Rest API with Swagger and NodeJS

Luigi Saetta

Introducing Swagger

Tony Tam

Swagger & OpenAPI Spec #openapi

Muhammad Siddiqi

Build and Manage Serverless APIs (APIDays Nordic, May 19th 2016)

3scale

Learn how to better communicate between Python services. We'll use simple-to-follow examples and go from a service with undocumented endpoints to one which has full docs and validation on requests. Learn how to use Swagger tooling for python, including the bravado (client) and pyramid_swagger (server) libraries. In the end, you'll (hopefully!) find nirvana and make the machines do all the hard work for you.

Crystal clear service interfaces w/ Swagger/OpenAPI

Scott Triglia

This presentation shows you how you can generate server stubs from a Swagger contract, configure the jaxrs-cxf language to enable Spring-configuration, Spring-Boot integration + tests, automatic BeanValidation on the server side, generate client code for java and javascript, use/integrate swagger-ui, use swagger2markup use custom Swagger-Codegen templates + how you can create your own language implementation.

How to generate a REST CXF3 application from Swagger ApacheConEU 2016

johannes_fiala

Swagger code motion talk

Victor Trakhtenberg

How to generate a rest application - DevFest Vienna 2016

johannes_fiala

Protect your users with Circuit breakers

Scott Triglia

Euroclojure2014: Schema & Swagger - making your Clojure web APIs more awesome

Metosin Oy

Swagger 2.0: Latest and Greatest

LaunchAny

FACTORES AMBIENTALES QUE ACTUAN EN "LA LAGUNA DE LOS MILAGROS"

Piero Caqui Guerra

Helps you to understand Swagger and its practical uses for representing REST APIs. You’ll learn some ways to get started. We’ll survey some of the tools and resources for describing REST APIs with Swagger. We’ll talk about what Swagger is (a specification and framework) — and isn’t (merely another doc tool). We’ll talk about the pros and cons of the Swagger-UI. And we’ll look at how Swagger helps people to learn about and explore an API.

A Tour of Swagger for APIs

Allen Dean

Consul in 5 minutes

Christophe Marchal

During the VOXXED Days in Berlin on 29 January 2016 Bernd Schönbach from LeanIX demonstrated an easy way to create well documented and implemented REST-APIs using the Dropwizard Library for the implementation and Swagger for easy Documentation. === LeanIX offers an innovative software-as-a-service solution for Enterprise Architecture Management (EAM), based either in a public cloud or the client’s data center. Companies like Adidas, Axel Springer, Helvetia, RWE, Trusted Shops and Zalando use LeanIX Enterprise Architecture Management tool. Free Trial: http://bit.ly/LeanIXFreeTrial

Simple REST-APIs with Dropwizard and Swagger

LeanIX GmbH

Consul

Ariel Moskovich

This session will show you how you can easily document your REST API's using Spring & Swagger. It will show you how to use the Swagger-Spring integration in a Spring Boot application: Setup a basic REST API using Spring-Boot together with Swagger-Springfox Access and test the REST-API using the Swagger-UI client Generate client code stubs for your language (e.g. Java, PHP, Python, ...) using Swagger-Codegen Graphically display your REST-API using the Chrome plugin Swagger.ed Devoxx Belgium Nov. 2015

Document your rest api using swagger - Devoxx 2015

johannes_fiala

Swagger for-your-api

Tony Tam

Andere mochten auch (18)

Rest API with Swagger and NodeJS

Introducing Swagger

Swagger & OpenAPI Spec #openapi

Build and Manage Serverless APIs (APIDays Nordic, May 19th 2016)

Crystal clear service interfaces w/ Swagger/OpenAPI

How to generate a REST CXF3 application from Swagger ApacheConEU 2016

Swagger code motion talk

How to generate a rest application - DevFest Vienna 2016

Protect your users with Circuit breakers

Euroclojure2014: Schema & Swagger - making your Clojure web APIs more awesome

Swagger 2.0: Latest and Greatest

FACTORES AMBIENTALES QUE ACTUAN EN "LA LAGUNA DE LOS MILAGROS"

A Tour of Swagger for APIs

Consul in 5 minutes

Simple REST-APIs with Dropwizard and Swagger

Consul

Document your rest api using swagger - Devoxx 2015

Swagger for-your-api

Kürzlich hochgeladen

Data spaces in distributed environments should be allowed to evolve in agile ways providing data space owners with large flexibility about which data they store. Agility and heterogeneity, however, jeopardize data exchanges because representations may build on varying ontologies and data consumers may not rely on the semantic correctness of their queries in the context of semantically heterogeneous, evolving data spaces. Graph data spaces are one example of a powerful model for representing and querying data whose semantics may change over time. To assert and enforce conditions on individual graph data spaces, shape languages (e.g SHACL) have been developed. We investigate the question of how querying and programming can be guarded by reasoning over SHACL constraints in a distributed setting and we sketch a picture of how a future landscape based on semantically heterogeneous data spaces might look like.

Shapes for Sharing between Graph Data Spaces - and Epistemic Querying of RDF-...

Steffen Staab

WSO2CON 2024 - Does Open Source Still Matter?

WSO2

WSO2Con2024 - From Code To Cloud: Fast Track Your Cloud Native Journey with C...

WSO2

%in ivory park+277-882-255-28 abortion pills for sale in ivory park

masabamasaba

Abortion Pills In Pretoria ](+27832195400*)[ 🏥 Women's Abortion Clinic In Pretoria ● Abortion Pills For Sale In Pretoria ● Pretoria 🏥🚑!! Abortion Clinic Near Me Cost, Price, Women's Clinic Near Me, Abortion Clinic Near, Abortion Doctors Near me, Abortion Services Near Me, Abortion Pills Over The Counter, Abortion Pill Doctors' Offices, Abortion Clinics, Abortion Places Near Me, Cheap Abortion Places Near Me, Medical Abortion & Surgical Abortion, approved cyctotec pills and womb cleaning pills too plus all the instructions needed This Discrete women’s Termination Clinic offers same day services that are safe and pain free, we use approved pills and we clean the womb so that no side effects are present. Our main goal is that of preventing unintended pregnancies and unwanted births every day to enable more women to have children by choice, not chance. We offer Terminations by Pill and The Morning After Pill.” Our Private VIP Abortion Service offers the ultimate in privacy, efficiency and discretion. we do safe and same day termination and we do also womb cleaning as well its done from 1 week up to 28 weeks. We do delivery of our services world wide SAFE ABORTION CLINICS/PILLS ON SALE WE DO DELIVERY OF PILLS ALSO Abortion clinic at very low costs, 100% Guaranteed and it’s safe, pain free and a same day service. It Is A 45 Minutes Procedure, we use tested abortion pills and we do womb cleaning as well. Alternatively the medical abortion pill and womb cleansing !!!

Abortion Pills In Pretoria ](+27832195400*)[ 🏥 Women's Abortion Clinic In Pre...

Medical / Health Care (+971588192166) Mifepristone and Misoprostol tablets 200mg

Abortion Pill Prices Tembisa [(+27832195400*)] 🏥 Women's Abortion Clinic in Tembisa ● Abortion Pills For Sale in Tembisa ● Tembisa 🏥🚑!! Abortion Clinic Near Me Cost, Price, Women's Clinic Near Me, Abortion Clinic Near, Abortion Doctors Near me, Abortion Services Near Me, Abortion Pills Over The Counter, Abortion Pill Doctors' Offices, Abortion Clinics, Abortion Places Near Me, Cheap Abortion Places Near Me, Medical Abortion & Surgical Abortion, approved cyctotec pills and womb cleaning pills too plus all the instructions needed This Discrete women’s Termination Clinic offers same day services that are safe and pain free, we use approved pills and we clean the womb so that no side effects are present. Our main goal is that of preventing unintended pregnancies and unwanted births every day to enable more women to have children by choice, not chance. We offer Terminations by Pill and The Morning After Pill.” Our Private VIP Abortion Service offers the ultimate in privacy, efficiency and discretion. we do safe and same day termination and we do also womb cleaning as well its done from 1 week up to 28 weeks. We do delivery of our services world wide SAFE ABORTION CLINICS/PILLS ON SALE WE DO DELIVERY OF PILLS ALSO Abortion clinic at very low costs, 100% Guaranteed and it’s safe, pain free and a same day service. It Is A 45 Minutes Procedure, we use tested abortion pills and we do womb cleaning as well. Alternatively the medical abortion pill and womb cleansing !!!

Abortion Pill Prices Tembisa [(+27832195400*)] 🏥 Women's Abortion Clinic in T...

Medical / Health Care (+971588192166) Mifepristone and Misoprostol tablets 200mg

%in kempton park+277-882-255-28 abortion pills for sale in kempton park

masabamasaba

We specialize in Psychic Readings, Psychic Love Spells, Binding Love Spells, Obsession Spells, Voodoo Spells, Lottery Spells, Marriage Spells, Black Magic Spells, Palm Readings & much more. Are you depressed? We perform this come-to-me love spell that works instantly with the aim of Winnipeg back the victim to the person performing the magic. Have you lost your lover? We perform this come-to-me love spell that works instantly with the aim of bringing back the victim to the person performing the magic. Have you lost your lover? Do u need to solve any relationship problem? Contact the powerful spells caster chief kule with love spells that work overnight and love spells that really work. Have you found yourself infatuated with a special someone you think could be the one? Are you looking for a spell to provide them with a nudge in the right direction? Or maybe the spell you cast didn’t achieve the results you were hoping for? Whether you’re new or versed in the ways of spell casting, we’re here to help. Today we’re going to provide you with a detailed guide on the types of love spells to cast. Not only that but there’s something for those who wish to find outside advice from more advanced spell casters. We’re also going to provide you with the top sites available to help you with your dilemma. Let’s begin our journey by educating ourselves on love magic and what a real love caster looks like. Love Magic and Love Casters Love magic made its first appearance back in Ancient Egypt and has been an active practice since. This type of magic is a branch of traditional magic and can be practiced in various ways. Typically the more common use of love magic is through the work of spells, but other methods look like Charms Rituals-LOVE Potions-Dolls and even Amulets If you are interested in becoming a love caster, be prepared for what’s to come. A genuine love caster knows that the art of love casting is no easy feat and shouldn’t be done casually. You should know that not only does it require you to be gifted spiritually, but you must be ready to serve others. Someone who is considered a real love caster has experience in all manner of spells, no matter the difficulty. Training yourself in attraction, commitment, and marriage spells is an excellent place to start. But this by no means will make you a professional. Practice your craft and expand your knowledge; understand that you will possess the ability to help others in time truly. Types of Love Spells What better way to start broadening your experiences with love spells than by learning more about them? These spells work like just about any other spell. Simply apply your intention, use a medium (sigils, mantras, candles, or charm bags), and top it off with establishing the belief that you will receive what you want. So what kind of spells are available and which ones suit your needs the best? Let’s take a look at the many options you have at your disposal. Attraction Spells

%+27788225528 love spells in Huntington Beach Psychic Readings, Attraction sp...

masabamasaba

Crypto Cloud Review - How To Earn Up To $500 Per DAY Of Bitcoin 100% On AutoP...

SelfMade bd

WSO2CON 2024 - Cloud Native Middleware: Domain-Driven Design, Cell-Based Arch...

WSO2

Conference: Engage2024 in Antwerp Type: Workshop Speakers: Florian Vogler, Henning Kunz, Christoph Adler Title: Navigating the Future with The Hitchhiker's Guide to Notes and Domino 14 Abstract: Embark on an exhilarating journey with industry trailblazers Florian Vogler, Henning Kunz, and Christoph Adler in this not-to-be-missed workshop at the forefront of the tech universe. Get ready for a thrilling kick-off as we navigate the current state of the HCL universe, setting the stage for an exploration of the groundbreaking Notes and Domino 14. Discover the latest enhancements and revolutionary features that will redefine your experience. In this interactive session, unlock a treasure trove of tips and tricks to elevate your utilization of version 14, both with and without the game-changing panagenda MarvelClient. Brace yourself for also diving into Nomad, Nomad Web, and VoltMX, expanding your horizons in the expansive HCL landscape. Be a part of this exclusive opportunity to stay ahead in the ever-evolving world of HCL technologies. Your journey to mastering Notes and Domino 14 begins here. And remember, in the spirit of intergalactic exploration, don't forget to bring your towel!

W01_panagenda_Navigating-the-Future-with-The-Hitchhikers-Guide-to-Notes-and-D...

panagenda

%in tembisa+277-882-255-28 abortion pills for sale in tembisa

masabamasaba

%in Midrand+277-882-255-28 abortion pills for sale in midrand

masabamasaba

%in Harare+277-882-255-28 abortion pills for sale in Harare

masabamasaba

%in Rustenburg+277-882-255-28 abortion pills for sale in Rustenburg

masabamasaba

%in tembisa+277-882-255-28 abortion pills for sale in tembisa

masabamasaba

Devoxx UK 2024 - Going serverless with Quarkus, GraalVM native images and AWS...

Bert Jan Schrijver

WSO2CON2024 - It's time to go Platformless

WSO2

WSO2CON 2024 - WSO2's Digital Transformation Journey with Choreo: A Platforml...

WSO2

Investing in AI transformation today The modern business advantage: Uncovering deep insights with AI Organizations around the world have come to recognize AI as the transformative technology that enables them to gain real business advantage. AI’s ability to organize vast quantities of data allows those who implement it to uncover deep business insights, augment human expertise, drive operational efficiency, transform their products, and better serve their customers

Microsoft AI Transformation Partner Playbook.pdf

Willy Marroquin (WillyDevNET)

Kürzlich hochgeladen (20)