github.com/go-swagger/go-swagger@v0.31.0/docs/presentations/swagger-golangsf.html (about) 1 <!DOCTYPE html> 2 <!-- saved from url=(0041)http://c43129cc.ngrok.io/golangsf.slide#1 --> 3 <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4 <title>Swagger</title> 5 <meta charset="utf-8"> 6 <script src="./swagger-golangsf_files/slides.js"></script> 7 <script> 8 9 if (window["location"] && window["location"]["hostname"] == "talks.golang.org") { 10 var _gaq = _gaq || []; 11 _gaq.push(["_setAccount", "UA-11222381-6"]); 12 _gaq.push(["b._setAccount", "UA-49880327-6"]); 13 window.trackPageview = function() { 14 _gaq.push(["_trackPageview", location.pathname+location.hash]); 15 _gaq.push(["b._trackPageview", location.pathname+location.hash]); 16 }; 17 window.trackPageview(); 18 window.trackEvent = function(category, action, opt_label, opt_value, opt_noninteraction) { 19 _gaq.push(["_trackEvent", category, action, opt_label, opt_value, opt_noninteraction]); 20 _gaq.push(["b._trackEvent", category, action, opt_label, opt_value, opt_noninteraction]); 21 }; 22 } 23 </script> 24 <meta name="viewport" content="width=1100,height=750"><meta name="apple-mobile-web-app-capable" content="yes"><meta name="chromesniffer" id="chromesniffer_meta" content="{"jQuery":"1.8.2","jQuery UI":"1.10.2"}"><script type="text/javascript" src="chrome-extension://homgcnaoacgigpkkljjjekpignblkeae/detector.js"></script></head> 25 26 <body style="display: none" class="loaded" data-feedly-mini="yes"> 27 28 <section class="slides layout-widescreen"> 29 30 <article class="current"> 31 <h1>Swagger</h1> 32 <h3>GolangSF, January 20, 2016</h3> 33 34 35 <div class="presenter"> 36 37 38 <p> 39 Ivan Porto Carrero 40 </p> 41 42 43 44 <p> 45 VMware 46 </p> 47 48 49 </div> 50 51 <div class="presenter"> 52 53 54 <p> 55 56 </p> 57 58 59 </div> 60 61 </article> 62 63 64 65 <article class="next"> 66 67 <h3>About me</h3> 68 69 70 <p> 71 Did a bunch of work on/with swagger: 72 </p> 73 74 75 <ul> 76 77 <li>Wrote scalatra</li> 78 79 <li>Worked at Reverb</li> 80 81 <li>Contributed async scala client to codegen</li> 82 83 <li>Wrote go-swagger</li> 84 85 </ul> 86 87 88 </article> 89 90 91 92 <article class="far-next"> 93 94 <h2>So you think you wanna microservice huh</h2> 95 96 </article> 97 98 99 100 <article class=""> 101 102 <h3>Read the source!</h3> 103 104 <div class="image"> 105 <img src="./swagger-golangsf_files/no-docs.jpg"> 106 </div> 107 108 109 </article> 110 111 112 113 <article class=""> 114 115 <h3>Stale documentation</h3> 116 117 <div class="image"> 118 <img src="./swagger-golangsf_files/stale-docs.jpg"> 119 </div> 120 121 122 </article> 123 124 125 126 <article class=""> 127 128 <h3>Lots of communication required</h3> 129 130 <div class="image"> 131 <img src="./swagger-golangsf_files/comm-failure.jpg"> 132 </div> 133 134 135 </article> 136 137 138 139 <article class=""> 140 141 <h3>Bottlenecks</h3> 142 143 <div class="image"> 144 <img src="./swagger-golangsf_files/staggered.jpg"> 145 </div> 146 147 148 </article> 149 150 151 152 <article class=""> 153 154 <h3>Customers don't want to write your SDK</h3> 155 156 <div class="image"> 157 <img src="./swagger-golangsf_files/burden.jpg"> 158 </div> 159 160 161 </article> 162 163 164 165 <article class=""> 166 167 <h3>All too often...</h3> 168 169 <ul> 170 171 <li>conflicts</li> 172 173 <li>blame game</li> 174 175 <li>Cover Your Ass</li> 176 177 </ul> 178 179 <div class="image"> 180 <img src="./swagger-golangsf_files/conflict.jpg"> 181 </div> 182 183 184 </article> 185 186 187 188 <article class=""> 189 190 <h3>Some requirements</h3> 191 192 193 <p> 194 Humans want <i>up to date</i> documentation to read 195 </p> 196 197 198 199 <p> 200 Consumers need an exhaustive contract 201 <br> 202 203 Different teams, different programming languages 204 </p> 205 206 207 208 <p> 209 Introspection would be a plus 210 <br> 211 212 DRY at application level would be nice 213 </p> 214 215 216 <div class="image"> 217 <img src="./swagger-golangsf_files/contract.jpg"> 218 </div> 219 220 221 </article> 222 223 224 225 <article class=""> 226 227 <h3>More sadness</h3> 228 229 <ul> 230 231 <li>many deploys, all the time</li> 232 233 <li>distributed system complexity</li> 234 235 <li>tooling relatively primitive</li> 236 237 </ul> 238 239 <div class="image"> 240 <img src="./swagger-golangsf_files/stoneage.jpg" height="400"> 241 </div> 242 243 244 </article> 245 246 247 248 <article class=""> 249 250 <h3>Enter swagger</h3> 251 252 253 <p> 254 Open standard on Linux Foundation 255 </p> 256 257 258 259 <p> 260 An interface to your service, described in <b>JSON</b> 261 </p> 262 263 264 265 <p> 266 A language/platform/deployment agnostic <b>contract</b> to your service 267 </p> 268 269 270 271 <p> 272 Enables "bigotry-free" restful design with emphasis on Getting Things Done. 273 </p> 274 275 276 277 <p> 278 Machine readable exhaustive contract of server abilities 279 </p> 280 281 282 283 <p> 284 Server controlled documentation 285 </p> 286 287 288 289 </article> 290 291 292 293 <article class=""> 294 295 <h2>You had me at tooling</h2> 296 297 </article> 298 299 300 301 <article class=""> 302 303 <h3>Orthogonal toolkit</h3> 304 305 <ul> 306 307 <li>spec validator with extra semantic validations</li> 308 309 <li>client generation</li> 310 311 <li>server generation</li> 312 313 <li>spec generation for <i>any</i> application</li> 314 315 <li>documentation lives with the code</li> 316 317 <li>go:generate integration</li> 318 319 </ul> 320 321 322 </article> 323 324 325 326 <article class=""> 327 328 <h3>Client SDKs </h3> 329 330 <ul> 331 332 <li>statically typed </li> 333 334 <li>regenerated imported on contract change</li> 335 336 <li>frontend and mobile client teams </li> 337 338 <li>other service clients</li> 339 340 <li><b>30+</b> languages through swagger-codegen</li> 341 342 </ul> 343 344 345 </article> 346 347 348 349 <article class=""> 350 351 <h3>Go Swagger server</h3> 352 353 <ul> 354 355 <li>Spec remains source of thruth</li> 356 357 <li>can be used as focal point of discussion/meetings</li> 358 359 <li>swagger meta data</li> 360 361 <li>routing</li> 362 363 <li>security</li> 364 365 <li>request validation</li> 366 367 <li>reuse <code>net/http</code> style middleware: `func(http.Handler) http.Handler`</li> 368 369 </ul> 370 371 372 <p> 373 <b>You</b> fill in the blanks, aka business logic. 374 </p> 375 376 377 378 </article> 379 380 381 382 <article class=""> 383 384 <h3>Spec generation </h3> 385 386 <div class="image"> 387 <img src="./swagger-golangsf_files/annotation.png"> 388 </div> 389 390 <div class="image"> 391 <img src="./swagger-golangsf_files/param-annotation.png"> 392 </div> 393 394 395 </article> 396 397 398 399 <article class=""> 400 401 <h3>Interaction with a Swagger API</h3> 402 <p class="link"><a href="http://www.getpostman.com/" target="_blank">Postman</a></p><p class="link"><a href="https://www.soapui.org/" target="_blank">SoapUI</a></p><p class="link"><a href="https://github.com/tikalk/commandcar#invoking-apis-using-commandcar" target="_blank">commandcar for instant CLI access</a></p> 403 <div class="image"> 404 <img src="./swagger-golangsf_files/postman.jpg"> 405 </div> 406 407 408 </article> 409 410 411 412 <article class=""> 413 414 <h3>Some resources</h3> 415 <p class="link"><a href="https://goswagger.io/" target="_blank">go-swagger documentation</a></p><p class="link"><a href="http://editor.swagger.io/" target="_blank">Swagger Editor</a></p><p class="link"><a href="http://petstore.swagger.io/" target="_blank">Swagger UI</a></p><p class="link"><a href="https://swaggerhub.com/" target="_blank">Swagger Hub (collaboration space)</a></p><p class="link"><a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md" target="_blank">Specification</a></p><p class="link"><a href="https://openapis.org/" target="_blank">Open API Initiative</a></p><p class="link"><a href="https://any-api.com/" target="_blank">Documentation and testconsoles for 175 APIs</a></p> 416 417 </article> 418 419 420 421 <article class=""> 422 423 <h3>What's next?</h3> 424 425 426 <p> 427 go-swagger going forward: 428 </p> 429 430 431 <ul> 432 433 <li>embrace http/2 entirely</li> 434 435 <li>integrate with swagger-codegen</li> 436 437 <li>stub generation</li> 438 439 <li>test generation</li> 440 441 <li>integration testing</li> 442 443 <li>httpie like CLI generation with optional syntax highlighting</li> 444 445 <li>more transports</li> 446 447 <li>scriptable handlers</li> 448 449 <li>more wireformats like protobuf, msgpack, ...</li> 450 451 </ul> 452 453 454 </article> 455 456 457 458 <article class=""> 459 <h3>Thank you</h3> 460 461 <div class="presenter"> 462 463 464 <p> 465 Ivan Porto Carrero 466 </p> 467 468 469 470 <p> 471 VMware 472 </p> 473 474 <p class="link"><a href="https://github.com/casualjim" target="_blank">https://github.com/casualjim</a></p><p class="link"><a href="http://twitter.com/casualjim" target="_blank">@casualjim</a></p> 475 </div> 476 477 <div class="presenter"> 478 479 480 <p> 481 482 </p> 483 484 485 </div> 486 487 </article> 488 489 <div class="slide-area" id="prev-slide-area"></div><div class="slide-area" id="next-slide-area"></div></section> 490 491 <div id="help" style="display: none;"> 492 Use the left and right arrow keys or click the left and right 493 edges of the page to navigate between slides.<br> 494 (Press 'H' or navigate to hide this message.) 495 </div> 496 497 498 <script src="./swagger-golangsf_files/play.js"></script> 499 500 501 <script> 502 (function() { 503 504 if (window["location"] && window["location"]["hostname"] == "talks.golang.org") { 505 var ga = document.createElement("script"); ga.type = "text/javascript"; ga.async = true; 506 ga.src = ("https:" == document.location.protocol ? "https://ssl" : "http://www") + ".google-analytics.com/ga.js"; 507 var s = document.getElementsByTagName("script")[0]; s.parentNode.insertBefore(ga, s); 508 } 509 })(); 510 </script> 511 512 513 <link rel="stylesheet" type="text/css" href="./swagger-golangsf_files/css"><link rel="stylesheet" type="text/css" href="./swagger-golangsf_files/styles.css"><div id="feedly-mini" title="feedly Mini tookit"></div></body></html>