github.com/rzurga/go-swagger@v0.28.1-0.20211109195225-5d1f453ffa3a/docs/presentations/devconpulse.slide (about)

     1  Swagger
     2  DevConPulse, April 23, 2016
     3  
     4  Ivan Porto Carrero
     5  Staff Engineer 2 @ VMware Cloud-Native Apps
     6  https://github.com/casualjim
     7  @casualjim
     8  
     9  * About me
    10  
    11  Did a bunch of work on/with swagger:
    12  
    13  - Wrote scalatra
    14  - Worked at Reverb
    15  - Contributed async scala client to codegen
    16  - Wrote go-swagger
    17  
    18  * So you think you wanna microservice huh
    19  
    20  * Read the source!
    21  
    22  .image images/no-docs.jpg
    23  
    24  * Stale documentation
    25  
    26  .image images/stale-docs.jpg
    27  .image http://gif.co/wsyy.gif
    28  
    29  * Lots of communication required
    30  
    31  .image images/comm-failure.jpg
    32  
    33  * Bottlenecks
    34  
    35  Teams have to wait for the API team to set up the endpoints.
    36  
    37  .image http://gif.co/wuLd.gif
    38  
    39  * Customers don't want to write your SDK
    40  
    41  .image images/burden.jpg
    42  
    43  * All too often...
    44  
    45  - conflicts
    46  - blame game
    47  - Cover Your Ass
    48  
    49  .image http://gif.co/wAik.gif
    50  
    51  
    52  * Some requirements
    53  
    54  Humans want _up_to_date_ documentation to read
    55  
    56  Consumers need an exhaustive contract
    57  Different teams, different programming languages
    58  
    59  Introspection would be a plus
    60  DRY at application level would be nice
    61  
    62  .image images/contract.jpg
    63  
    64  
    65  * More sadness
    66  
    67  - many deploys, all the time
    68  - distributed system complexity
    69  - tooling relatively primitive
    70  
    71  .image images/stoneage.jpg 400 _
    72  
    73  * Enter swagger
    74  
    75  Open standard on Linux Foundation
    76  
    77  An interface to your service, described in *JSON*
    78  
    79  A language/platform/deployment agnostic *contract* to your service
    80  
    81  Enables "bigotry-free" restful design with emphasis on Getting Things Done.
    82  
    83  Machine readable exhaustive contract of server abilities
    84  
    85  Server controlled documentation
    86  
    87  .image http://gif.co/wAiL.gif
    88  
    89  
    90  * You had me at tooling
    91  
    92  * Orthogonal toolkit
    93  
    94  - spec validator with extra semantic validations
    95  - client generation
    96  - server generation
    97  - spec generation for _any_ application
    98  - documentation lives with the code
    99  - go:generate integration
   100  
   101  .image http://gif.co/pbvn.gif
   102  
   103  * Client SDKs
   104  
   105  - statically typed
   106  - regenerated imported on contract change
   107  - frontend and mobile client teams
   108  - other service clients
   109  - *30+* languages through swagger-codegen
   110  
   111  .image http://gif.co/vMhD.gif
   112  
   113  * Go Swagger server
   114  
   115  - Spec remains source of thruth
   116  - can be used as focal point of discussion/meetings
   117  - swagger meta data
   118  - routing
   119  - security
   120  - request validation
   121  - reuse `net/http` style middleware: `func(http.Handler) http.Handler`
   122  
   123  *You* fill in the blanks, aka business logic.
   124  
   125  .image http://gif.co/wxo3.gif
   126  
   127  * Spec generation
   128  
   129  .image images/annotation.png
   130  .image images/param-annotation.png
   131  
   132  * Interaction with a Swagger API
   133  
   134  .link http://www.getpostman.com/ Postman
   135  .link https://www.soapui.org/ SoapUI
   136  .link https://github.com/tikalk/commandcar#invoking-apis-using-commandcar commandcar for instant CLI access
   137  
   138  .image images/postman.jpg
   139  
   140  * Some resources
   141  
   142  .link https://goswagger.io go-swagger documentation
   143  .link http://editor.swagger.io/ Swagger Editor
   144  .link http://petstore.swagger.io/ Swagger UI
   145  .link https://swaggerhub.com/ Swagger Hub (collaboration space)
   146  .link https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md Specification
   147  .link https://openapis.org/ Open API Initiative
   148  .link https://any-api.com/ Documentation and testconsoles for 175 APIs
   149  
   150  
   151  * What's next?
   152  
   153  go-swagger going forward:
   154  
   155  - embrace http/2 entirely
   156  - integrate with swagger-codegen
   157  - stub generation
   158  - test generation
   159  - integration testing
   160  - httpie like CLI generation with optional syntax highlighting
   161  - more transports
   162  - scriptable handlers
   163  - more wireformats like protobuf, msgpack, ...