We recently held a free Swagger training, Adding Swagger to Your Existing APIs: How to Automate a ‘Code First’ to OAS at Scale, in which we looked at different tools and strategies for generating and hosting an OpenAPI Specification (OAS) for existing APIs.
During the webinar, we received a ton of questions related to the different options that are out there for teams developing APIs in a wide range of languages. We also received additional questions about how Swagger tools can help, and how teams can coordinate different approaches to API development with OAS.
As a follow up to the webinar, we wanted to share links to some of the different annotation libraries for working with OAS as well as answer some of the top questions from Swagger users at the event.
We have APIs developed in Java, C#, Python, etc. Where can I find the best annotation libraries for these languages?
The OpenAPI Specification (OAS) and Swagger tools both have active communities of developers that use and develop new tools to support your API development. The Swagger team supports some of these libraries for generating OAS from your existing APIs, and the rest our maintained by the OAS community:
You can explore other open source tools that support OAS here.
Where can I read more about storing definitions in SwaggerHub with Gradle or Maven?
SwaggerHub offers two core plugins for automating the export of generated OAS definitions into the platform.
These plugins support:
-
Authentication with an API key for restricted operations (e.g submitting a definition to a private organization).
-
Connecting to the SwaggerHub cloud version by default or an on-premise SwaggerHub instance through optional configuration.
Learn more about the Gradle Plugin here.
Learn more about the Maven Plugin here.
We use the Swagger Codegen project for generating server stubs, is there a reason we should be using SwaggerHub to do this?
SwaggerHub was created by the same team behind the Swagger Codegen project. In fact, the code generation functionality in SwaggerHub runs on the contributions of the open source project.
SwaggerHub provides one central platform for your team to work together on your API development with OAS. Rather than having individual developers working in isolation with the open source tools installed on their local machines - or managing complex build processes to support this at scale, SwaggerHub provides a single platform to host OAS definitions, collaborate on the design and documentation of your APIs, as well as generate server stubs and SDKs with the built-in code generation functionality.
SwaggerHub also ties into the tools you trust to develop APIs, whether you need to push to an API gateway, trigger a Jenkins build, or sync with your source control host, SwaggerHub provides native integrations and plugins to fit your workflow.
What languages are supported for OAS 3.0 code generation in SwaggerHub?
We are continuing to roll out support for new languages in SwaggerHub. Here is the latest update on supported languages for OAS 3.0:
Clients
-
Dynamic-html
-
Html
-
Html2
-
Java
-
Jaxrs-cxf-client
-
Kotlin-client
-
Php
-
Scala
-
Swift3
-
Swift4
-
Typescript-angular
Server Stubs
-
Jaxrs-resteasy
-
Jaxrs-resteasy-eap
-
Scala-akka-http-server
-
Spring
What happens to the specification when there are changes to the API, does it automatically update the existing spec document in SwaggerHub?
By connecting source code to a platform like SwaggerHub – it's possible to keep an external specification in line with the generated version that is part of the build process. Beyond this SwaggerHub has a robust versioning system, allowing multiple teams, projects or changes to be intelligently catalogued and stored in a single source of truth.
Regarding API Gateway deployments, do you have the ability within the definition to add in validation directly alongside being added to the spec?
This functionality typically doesn’t fall into the definition itself – we would hand the OAS that is generated off to a file that would execute a series of requests, and validate them against the defined responses. There are code focused solutions like the Swagger Test Template project, as well a number of GUI driven solutions that allow the import of OAS and easy generation of tests such as ReadyAPI.
Is there a way to convert SwaggerHub comments to JIRA tasks?
At this time we don’t have a direct integration to JIRA. The SwaggerHub team is constantly adding to the list of supported tools and platforms as we take on feedback from users and organizations.
Learn how to automate your 'code first' approach at scale.
You can watch the full recording of the training here.
When you're ready, SwaggerHub is helping teams of all sizes coordinate their API development with OAS — whether you are starting a new project with a design first approach, or looking to document an existing set of APIs with a code first approach.
Get started for free today.