SwaggerHub Getting Started: Account, Keys, and First Call

Getting started overview

Getting started with SwaggerHub primarily involves creating an account, designing an API specification, and then utilizing the platform's features for documentation and code generation. SwaggerHub is a web-based platform for designing and documenting APIs that adhere to the OpenAPI Specification. It provides a collaborative environment for teams to define, validate, and manage their API contracts.

The initial setup focuses on gaining access to the platform and understanding its core interface for API definition. Unlike platforms that primarily focus on making requests to existing APIs, SwaggerHub emphasizes the design-first approach, where the API's contract is established before implementation. This process typically includes:

• Account creation and initial login.
• Understanding the SwaggerHub dashboard and project organization.
• Creating a new API definition or importing an existing one.
• Using the integrated editor to define API paths, operations, parameters, and responses.
• Generating client SDKs or server stubs based on the API definition (optional, but a core feature).

The goal of this guide is to navigate these steps to enable a user to define their first API specification within SwaggerHub.

Create an account and get keys

To begin using SwaggerHub, you need to create an account. SwaggerHub offers a free tier that supports up to three APIs and one user, suitable for individual developers or small projects. Paid plans provide additional features for teams, including more users, private APIs, and advanced collaboration tools.

1. Navigate to the SwaggerHub website: Go to the SwaggerHub homepage.
2. Sign up: Click on the "Get Started Free" or "Sign Up" button. You can typically sign up using an email address or by integrating with a third-party identity provider like Google.
3. Account verification: Follow the on-screen prompts to verify your email address, if required.
4. Log in: Once your account is created and verified, navigate to the SwaggerHub login page and enter your new credentials.

API Keys and Tokens

SwaggerHub uses API keys and personal access tokens for programmatic access to its features, such as integrating with CI/CD pipelines or custom scripts. For initial API design and editing within the web interface, an API key is not immediately required. However, if you plan to automate tasks or integrate SwaggerHub with other tools, you will need to generate a personal access token.

1. Access Profile Settings: After logging in, click on your profile avatar in the top right corner and select "Settings".
2. Generate Personal Access Token: In the settings menu, navigate to the "Personal Access Tokens" section.
3. Create New Token: Click "Create New Token", provide a descriptive name for the token, and define its expiration and scopes. Scopes determine what actions the token can perform (e.g., read APIs, write APIs, manage organizations). For general programmatic access, selecting appropriate read and write scopes for APIs might be necessary.
4. Save Token: Copy the generated token immediately. It will only be displayed once. Store it securely, as it functions as bearer authentication for the SwaggerHub API endpoints.

Your first request

In SwaggerHub, "making a request" typically refers to defining an API operation and then using the integrated "Try it out" feature to simulate a call, rather than an external HTTP request using a client like curl or Postman. The platform focuses on the design and documentation aspect of the API lifecycle.

Creating a New API Definition

This process outlines creating a basic API definition to understand the editor and the "Try it out" functionality.

1. Create a New API: From your SwaggerHub dashboard, click the "Create New API" button.
2. Configure API Details:
   • Name: Provide a unique name for your API (e.g., MyFirstAPI).
   • Version: Specify the initial version (e.g., 1.0.0).
   • Definition Type: Choose "OpenAPI 3.0" or "OpenAPI 2.0 (Swagger 2.0)". OpenAPI 3.0 is generally recommended for new projects.
   • Template: You can start from a blank template or select an example. For this guide, starting with a basic template is sufficient.
   • Visibility: Choose "Public" or "Private" (private APIs require a paid plan or a specific organizational setup).
3. Open the Editor: Click "Create API". This will open the SwaggerHub editor, showing a YAML or JSON representation of your API definition on the left and a rendered documentation preview on the right.

Defining a Simple Endpoint

Let's add a simple GET endpoint to your API definition.

1. Locate the paths section: In the YAML/JSON editor, find the paths: key.
2. Add a new path: Below paths:, add a simple endpoint, for example, /greet.
3. Define a GET operation: Under /greet, add a get operation with a summary and a response. For example:
   

   paths:
     /greet:
       get:
         summary: Returns a greeting message
         responses:
           '200':
             description: Successful response
             content:
               application/json:
                 schema:
                   type: object
                   properties:
                     message:
                       type: string
                       example: Hello, SwaggerHub!

4. Save Changes: SwaggerHub typically auto-saves, but ensure no errors are indicated in the editor.

Using "Try it out"

The "Try it out" feature allows you to test your defined API operations directly from the Swagger UI documentation generated by SwaggerHub.

1. Navigate to the Documentation View: On the right side of the SwaggerHub editor, you should see the rendered documentation. Scroll down to find your new /greet endpoint.
2. Expand the Operation: Click on the GET /greet operation to expand its details.
3. Click "Try it out": Below the summary and responses, you will see a "Try it out" button. Click it.
4. Execute the Request: Click the "Execute" button.
5. Review the Response: The Swagger UI will simulate a request and display a "Server response" section, including the curl command, request URL, response body, and response headers. Since this is a client-side simulation based on your API definition's examples, the response will reflect the example value you defined (e.g., {"message": "Hello, SwaggerHub!"}).

Common next steps

After defining your first API and understanding the "Try it out" feature, several common next steps can enhance your API development workflow:

• Version Control Integration: Connect your API definition to a source control system like GitHub, GitLab, or Bitbucket. This allows you to manage versions, collaborate on changes, and maintain a history of your API's evolution. SwaggerHub's version control integrations streamline this process.
• API Gateway Integration: Integrate your SwaggerHub API definition with an API Gateway (e.g., AWS API Gateway, Azure API Management, Kong Gateway). This enables you to deploy your API definition directly to the gateway, configuring endpoints, security, and routing rules based on your OpenAPI file. For example, AWS API Gateway supports importing OpenAPI definitions.
• Code Generation: Utilize the OpenAPI Generator integrated within SwaggerHub to generate client SDKs in various programming languages (e.g., Python, Java, JavaScript) or server stubs. This accelerates development by providing boilerplate code directly from your API definition.
• Team Collaboration: Invite team members to collaborate on your API design. SwaggerHub offers features for commenting, versioning, and resolving conflicts in a shared environment.
• Style Validation: Implement API style guides to ensure consistency across your API definitions. SwaggerHub can enforce these rules, helping maintain API quality and governance.
• Domain Management: For larger organizations, defining and managing domains (reusable components like schemas or parameters) can improve consistency and reusability across multiple APIs.

Troubleshooting the first call

When you encounter issues during your first interactions with SwaggerHub, especially when using the "Try it out" feature or defining your API, consider the following common troubleshooting steps:

• YAML/JSON Syntax Errors: The most frequent issue is incorrect syntax in your OpenAPI definition. The SwaggerHub editor provides real-time validation and will highlight errors with red underlines or warning messages. Check for:
  • Incorrect indentation (YAML is sensitive to whitespace).
  • Missing colons or hyphens.
  • Typos in keywords (e.g., paths, get, responses, schema).
  • Mismatched curly braces {} or square brackets [] in JSON.

  Refer to the OpenAPI Specification documentation for correct structure and syntax.

• Definition Not Saving/Updating: Ensure your changes are saved. While SwaggerHub often auto-saves, network issues or browser problems can interfere. Look for a "Saved" indicator or manually save if an option is available. If you see persistent errors, the API definition might not be valid, preventing a successful save.
• "Try it out" Not Working as Expected:
  • No Response/Incorrect Response: The "Try it out" feature simulates a response based on the responses section of your OpenAPI definition. If you don't see an expected response, ensure your operation has a 200 (or relevant success code) response defined with an accurate description and, ideally, an example payload. The generated response will directly reflect these examples.
  • Parameters Not Appearing: If your operation expects parameters (e.g., path, query, header), ensure they are correctly defined under the parameters section of your operation, including name, in (path, query, header, cookie), required, and schema.
• Authentication Issues with API Tokens: If you are using a personal access token for programmatic access and encounter 401 Unauthorized or 403 Forbidden errors:
  • Verify the token is correct and hasn't expired.
  • Check that the token has the necessary scopes (permissions) for the API call you are attempting.
  • Ensure the token is included in the Authorization: Bearer <YOUR_TOKEN> header of your request.
• Browser Caching: Sometimes, browser caching can lead to outdated views. Try clearing your browser's cache or opening SwaggerHub in an incognito/private browsing window to rule out client-side issues.
• Referencing External Components: If you are referencing external schemas or components using $ref, ensure the paths are correct and accessible. If these are internal to SwaggerHub, verify the component names match exactly.