Open discussions on specific topics selected by the Software Working Group and selected from the list of SWG Topics For Discussion.
OpenAPI (f.k.a. Swagger) Specification tools and Frameworks
Moderated by Sandeep Puthanveetil Satheesan
We'll start with a brief background on OpenAPI Specification (formerly known as the Swagger Specification) and go through some of the main elements of its documentation. Then, we'll hear from the participants about the different Open API tools and frameworks they use to design, develop and document Application Programming Interfaces (APIs) and their experiences using those.
Recording: https://uofi.box.com/s/ef9akyqdefvvwt900fu5tzmhucivpslk
Slides: 
SD Round Table OpenAPI.pptx
Attendees:
Luigi Marini
Jong Lee
Sandeep Puthanveetil Satheesan
Andrew Manning
Charles Blatti
Rebecca Eveland
Jeff Terstriep
Rob Kooper
Scott Koranda
Sara Lambert
Chris Navarro
Max Burnette
Matt Berry
Yong Wook Kim
Chen Wang
Lisa Yanello
Discussion:
Sandeep gave a brief history of OAS. There is a video of the history noted in the slides if you want more information. Discussion of Swagger vs Open API. FastAPI is used in Clowder and it automatically generates the codes.
Jeff notes that it depends on how tightly the API is tied to the backends.
Andrew notes: This is a more practical and accessible documentation of the spec I reference frequently: https://swagger.io/docs/specification/about/
There was deep discussion about Swagger and other tools - OpenAPI supported toolds are swagger, postman and swaggerhub. redocly
Sara notes: Spring Boot in Java works the same way - an OpenAPI spec is automatically produced based on the endpoints that you write
Helpful, but it can definitely be frustrating
Does anyone use testing with API? Are these use cases or can they be used across the board?
Rebecca notes: The Rails gem for OpenAPI has you write the API spec in the code using Ruby structure, so it’s not “automatic” but it will (hypothetically) generate a complete OpenAPI file.
Rob notes: https://github.com/stoplightio/prism is the code I was mentioning about the mock server.
Sara notes: that sounds similar to Spring Boot and needing to add annotations to all of the code
https://github.com/bodom0015/swagger-k8s-crd-codegen
Example of the frontend sync/regenerate directives that I mentioned: https://github.com/nds-org/workbench-webui/blob/develop/package.json#L72-L76
Tools that develop frameworks: Python Connexion, FastAPI, Swagger Codegen
Connexion is a tool that works as well. Discussion followed re: which framwork/tools work best.
Sandeep shared OAI/OpenAPI-Specification on GitHub.
Moving to documentation, OpenAPI-Implementation on GitHub (swagger, redocly)
Rob notes that https://apiary.io/ is a powerful API design stack for developers. And: https://brapigenotyping21.docs.apiary.io/#/reference/call-sets/get-callsets/get-callsets/200?mc=reference%2Fcall-sets%2Fget-callsets%2Fget-callsets%2F200
If you are interested in contributing to a Round Table, please see these links:
Round Table Google Sheet: https://docs.google.com/spreadsheets/d/1kbgO6sIb_4eLugfSVKQNCTXdaKp1R6m0RDczPTsUAoQ/edit#gid=0 Every one should have edit permission.