If you already have a SwaggerHub account, you can login with those credentials. Signing up (or logging in, if you have an account) allows you to save your call history, pin requests, use collections, and create API definitions. You can have up to 3 definitions in our free plan. You can also login using your GitHub credentials. We use single sign on, so GitHub stores and maintains your credentials if you choose the GitHub option. You will NOT have a Swagger username or password if you choose the GitHub option when you sign up.
How to Make an API call
Near the top of the page, there is a method dropdown containing common HTTP verbs like GET, PUT, and POST. Choose the method you’d like to use. To the right of the method option is the URI input. Choose the base URI and path of the API you’d like to call. You can put local resources there, as well (e.g. localhost:8080). If you don’t have any authentication, headers, or query parameters to add, press SEND! SEND will turn green once you’ve put a destination into the URI field. If you get an error back, please see our Browser Support section for tips.
Authentication, Parameters & Headers
Below the URI input are three tabs, Parameters, Authentication & Headers, and Body. Parameters refers to query parameters, e.g. www.google.com?search=star%20wars, where search is a query parameter and the value being searched for is ‘star wars.’ Whether you add a query parameter directly to the URI, or put it into the query parameter area in the tabs, we’ll convert it for you and show query parameters in both places (don’t worry, it won’t be duplicated across the wire). Authentication & Headers is where you’d go to add headers, like the content-type of a request, and add authentication. If you choose Basic authentication, we’ll give you a username and password input and encode those for you. For Oauth2 or JWT, we’ll add the Authorization: Bearer header and ask you for the token to include. For other types of authentication, feel free to add your authentication headers independent of the Authentication dropdown (choose no authentication, even though you’ll add it). Body is the section where you’ll add your request body, if you’re using a method that needs a body. (GET, for instance, will not allow you to specify a body, since that HTTP method disallows it and is read-only).
The USE DEFINITION feature lets you mock or make API calls to an API based on the API definition. We support both OpenAPI version 2 and WSDL files. You can put the URL of a hosted OpenAPI file in the URI input field, or submit a file through USE DEFINITION, and press SEND to parse the definition file. To see an example, choose TRY A LINK to have Swagger Petstore’s link filled into the URI input. Then, press SEND. Next, go to USE DEFINITION to see the API calls you can make listed. Clicking on any of the method/path combinations will fill the information into the request portion of the tool so that you can press SEND to make the call. Choose BACK to select another definition.
History & the Right Panel
The right panel of Inspector is collapsible, with the arrow near the top right being clickable. Once clicked, the arrow will reverse direction to expand the pane when clicked again. The History stores 1000 requests, deleting the oldest requests as new requests are made. You must select entries from your History or Collections to activate the buttons (e.g. CREATE API DEFINITION).
To pin a request, first ensure you’re logged in. Next, make an API call, if you haven’t already. In the History pane on the right, you will see a little thumbtack to the right of each request. Click on it if you want to pin it to the top of your history, and click the thumbtack again if you want to remove it. A green thumbtack indicates that you’ve pinned a request successfully. Requests will appear in each section (pinned and unpinned) chronologically, with the most recent requests first. There can be a maximum of 100 pinned requests. Pinned requests will not be deleted unless you take action to do so - they are exempt from the automatic deletion of the oldest History requests.
First, make sure you’re logged in to use Collections (no point saving something if it’s not persistent or present in an account for you to come back to). Second, select any number of requests from your History (pinned or unpinned, or both), and select ADD TO COLLECTION. Next, select an existing Collection from the dropdown menu, or create a new Collection (CREATE NEW COLLECTION) to add the requests to. Once you click ADD TO COLLECTION, your requests will be added. You can toggle to the Collections tab to find your Collections. Collections can be expanded and collapsed using the arrows. There can be a maximum of 100 requests in a single Collection.
We fully support Chrome and Firefox. You should be prompted to download the extension if you’re using either. The extension allows cross origin resource sharing (CORS), which is typically disallowed in browsers. This allows your browser to access information from servers outside of the website you’re on, and thus to make an API call. Some APIs may still accept the transmission, but many will deny the request without the plugin to set user agent headers. For the best experience, we highly recommend downloading the extension. Click ADD EXTENSION on both prompts below to get it. If you use Safari, the developer tools can be useful to get around errors. In particular, “Disable Cross-Origin Restrictions” is recommended to avoid CORS errors. See this Safari guide for more info. For now, we don’t officially support Opera or other browsers, because we haven’t yet built an extension to handle CORS issues for each of them. However, Inspector will still work when calling some APIs that don’t have CORS restrictions. Many browsers have plugins that can bypass CORS restrictions, so we would recommend trying that if you’re getting errors and don’t want to switch browsers.
If you’re using Chrome or Firefox, the Swagger Inspector Extension can get around many errors you could have, especially CORS (cross origin resource sharing) issues. You should be prompted to download the extension, but if not, the Chrome extension can be found here, and the Firefox extension can be found here. If you’re using Safari, the developer tools can be useful to get around errors. In particular, “Disable Cross-Origin Restrictions” is important to select. See this Safari guide for more info. Generic “Request Failed” messages often indicate an issue with the API being behind a firewall or a CORS issue. Our first recommendation would be to download the extension for Chrome or troubleshoot with Safari’s developer options. If you’re using another browser, we’d recommend using either Chrome or Safari for the best experience (and as a troubleshooting step). For other HTTP errors, see this HTTP status code list and troubleshooting guide. For any feedback or to report issues, email firstname.lastname@example.org.