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

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