Home Blog SwaggerHub 101 Recap...

SwaggerHub 101 Recap: Answers to Your Top SwaggerHub Questions

Ryan Pinkham
  October 04, 2016

We recently introduced free training for SwaggerHub users. These trainings are designed to help you get the most from SwaggerHub by introducing you to SwaggerHub's different features, and the capabilities of the platform. You can find the full list of upcoming SwaggerHub 101 trainings here. As part of the training, attendees have the chance to have their questions answered from members of the SwaggerHub team. Here is a recap of the top questions we received at a recent SwaggerHub 101 training:

What is "Show Comments" and how does it work?

The Comments feature is one of SwaggerHub’s built-in collaboration capabilities that lets different stakeholders comment on the API definition within the SwaggerHub Editor. Collaborators can be assigned specific roles, based on the amount of access they’ll need to participate in the API design process. For example, collaborators can be given the ability to edit the API (Editor), comment on individual lines of the Swagger specification (Commentator), or simply view the API (Viewer). Use comments to discuss ideas or point to issues in specific lines of your API definition in the SwaggerHub editor. comments Comments can be used to share feedback or raise issues, and can be marked as open or resolved. The “Show Comments” button will show all comments, both open and resolved. Learn more about collaborating with SwaggerHub.

Does SwaggerHub support JSON or YAML?

SwaggerHub supports the Swagger (Open API) 2.0 syntax for describing APIs. The default format of API definitions is YAML. You can paste JSON text as well, but it will be converted to the YAML format when you save your API definition. You can download your Swagger specifications in both formats (YAML and JSON).

What happens when I publish the API in SwaggerHub?

Publishing is a way to tell people that the API is in a stable state, it is going to work as designed and is ready to be consumed by applications.  When you publish an API on SwaggerHub, that API becomes read-only and can only be edited if the API is unpublished again. It is OK to unpublish an API temporarily if you need to improve the description text or fix typos. But for breaking changes — like new operations or parameters — you should start a new version instead by using the Add Version command in the SwaggerHub editor. SwaggerHub lets you maintain multiple versions of an API specification, so you can work on the next API version while keeping the published version (the “production” version) intact. Learn more about publish APIs on SwaggerHub.

What are the integrations available in SwaggerHub?

SwaggerHub is built for teams to collaborate across the entire API lifecycle. As a result, SwaggerHub supports the tools teams rely on to develop APIs. These integrations include: Learn more about SwaggerHub’s available integrations.

How do I mock an API backend server?

SwaggerHub integrates with VirtServer, which is part of the SmartBear Ready! API virtualization product. When enabled, the VirtServer Integration automatically creates and maintains a semi-static mock of an API defined in SwaggerHub. This mock is updated every time you save the API, meaning you no longer have to find and use external tools to create mock services. You can efficiently iterate on the design with your team with the preview generated by the VirtServer, all with a couple of clicks. The mock server can be a powerful tool when deliberating on the API design. Without writing a line of code, you can allow API consumers to develop clients against the VirtServer, which is guaranteed to respond with compatible, realistic payloads. Learn more about mocking an API with SwaggerHub.

How does SwaggerHub help with documenting my API?

SwaggerHub can provide the following with regards to documentation.
  1. Users can define and document every aspect of the API directly on the Swagger Editor, and can see them rendered visually for end consumers to work with, understand and integrate with in the Interactive Docs tab.
  2. Users can generate a basic dev portal-like interface with our in-built HTML download of the API. You can download a bootstrapped version of your API’s documentation which shows your end points with 6 different client SDKS, and you can always add more.   
swaggerpetstore2 Follow the steps to get your HTML render: Step 1: Go to one of your valid APIs on SwaggerHub Step 2: Click on the download icon on the top right corner, and choose the html2 option from the client side download publish-swagger Step 3:  Download the zip file to a known location on your local machine. Go to the download location, unzip the folder, and open the HTML file present in the downloaded, unzipped folder.

Are there plans to offer a deployed version that could connect to on-prem SCM systems?

Yes. There is an on-premise version of SwaggerHub, already available. This is part of the Enterprise SwaggerHub plan. The best way to find out if the on-premise version can work for your organization is to reach out the SwaggerHub team directly at [email protected].

Miss the training? Watch it on-demand.

Or register for an upcoming training.
Have additional SwaggerHub questions? Shoot us an email at [email protected] or reach out to us on Twitter: @SwaggerHub.

You Might Also Like