Skip to Content
Developer StudioDesign API Specs

📜 API Spec Management in Developer Studio (ATA)

The API Spec section in ATA’s Developer Studio is where you define and manage the OpenAPI specifications for your API applications. This section allows you to write, edit, and validate your API specifications using multiple views, making it easier to design APIs that adhere to industry standards.

ATA provides a variety of views to work with your OpenAPI Spec, including Code View, Form View, Swagger View, and Preview. Additionally, error tracking and validation are built into the workflow, ensuring that your API specs are properly formatted and compliant.

🔑 What is the API Spec Section?

The API Spec section in ATA’s Developer Studio allows you to define the structure, endpoints, parameters, responses, and other essential details of your API using the OpenAPI Specification (also known as Swagger). ATA’s API Spec editor offers multiple views to cater to different user preferences, whether you’re comfortable with raw code, form-based inputs, or need to visualize the spec in a Swagger-like interface.

Key Features:

  • Multiple Views: Code View, Form View, Swagger View
  • Error Tracking: Identifies validation issues and warnings
  • Spec Preview: Preview the API Spec layout before publishing
  • Error Tracking with Spectral Rules: Enforces validation and compliance with API governance rules

🧑‍💻 How to Work with API Spec in Developer Studio

Step 1: Navigate to the API Spec Tab

Once you’ve created an API application in Developer Studio, go to the API Spec Tab where you will define your OpenAPI Spec.

  • You can either import the OpenAPI Spec from an external source (e.g., Git repository, API Gateway) or write it manually.

Step 2: Choose the View Mode

ATA provides several views to work with your OpenAPI Spec. Each view caters to different preferences and user needs.

1. Code View (JSON and YAML)

  • In Code View, you work directly with the raw JSON or YAML format of the OpenAPI Spec.
  • This view is best suited for developers comfortable with the specification syntax and those who want full control over the API spec.
  • Example (in JSON format): 
    {
  "openapi": "3.0.0",
  "info": {
    "title": "My API",
    "version": "1.0.0"
  },
  "paths": {
    "/users": {
      "get": {
        "summary": "Returns a list of users",
        "responses": {
          "200": {
            "description": "A list of users"
          }
        }
      }
    }
  }
}

2. Form View

  • Form View presents the OpenAPI Spec in an interactive form layout.
  • This view allows you to fill in fields such as title, version, paths, and parameters without manually writing the JSON/YAML syntax.
  • Form View is ideal for non-developers or users who prefer an intuitive interface for creating and editing API specs.
  • You’ll see fields for adding API details, request parameters, and response models in a structured, form-like interface.

3. Swagger View

  • Swagger View displays the OpenAPI Spec in a visual, Swagger-like interface.
  • This view allows you to interact with your API spec as if it were loaded into the Swagger UI, making it easier to visualize and navigate your API structure.
  • Swagger View is useful for reviewing and testing the endpoints directly from the spec.

4. Preview Tab

  • The Preview Tab shows a live preview of how the OpenAPI Spec will render.
  • This helps you visualize how the spec will look once published, ensuring that your API specification is structured and rendered properly before it goes live.
  • It provides a real-time view of your API endpoints and can help in identifying any layout or structural issues before finalizing the spec.

⚠️ Error Tracking and Validation

One of the critical aspects of working with OpenAPI Specs in ATA is error tracking and validation. As you work on your API spec, ATA automatically checks for errors and compliance issues using Spectral Rules defined in API Governance.

Error Tracking Features:

  • Validation Errors: ATA identifies issues such as missing fields, incorrect data types, and other structural problems in the OpenAPI Spec.
  • Warnings: ATA will highlight areas that might cause issues but don’t necessarily break the specification. These could be related to deprecated fields, missing documentation, or minor compliance issues.
  • Important Information: If ATA detects important issues (e.g., security risks or significant missing components), it will show a notification in the Error Tab to ensure that you address these before publishing the spec.

Example Error Message:

  • Missing description for a response.
  • Invalid data type for a status_code parameter.
  • Deprecated field in the OpenAPI Spec.

🔍 Working with Spectral Rules for Validation

Spectral Rules are part of the API Governance feature in ATA. These rules define the best practices and standards for your OpenAPI Spec, ensuring that your API definitions comply with industry standards.

  1. Apply Spectral Rules:

    • Spectral Rules are applied to your OpenAPI Spec to automatically validate the spec against predefined standards.
    • These rules include checks for common API issues such as:
      • Missing or incorrect data types
      • Missing required fields
      • Use of deprecated fields
      • API security headers

  2. Error Tab:

    • Any errors, warnings, or important information related to Spectral Rule violations will appear in the Error Tab.
    • ATA helps you ensure that your OpenAPI Spec is compliant, reducing the risk of misconfigurations or security vulnerabilities.

🔄 Managing and Publishing API Spec

Once your OpenAPI Spec is complete and validated:

  1. Save the API Spec:

    • After making changes in the Form View, Code View, or Swagger View, you can save the API spec within ATA.

  2. Publish the API Spec:

    • Once you are satisfied with the spec, you can publish it, making it available for use in your API application.
    • This allows you to integrate the API definition into the rest of your development and testing workflows.

  3. Versioning:

    • ATA keeps track of versions, so you can update your API spec as your application evolves while preserving the previous versions for reference and compatibility.

📝 Final Notes on API Spec in Developer Studio

The API Spec section in ATA’s Developer Studio is a central part of API design and governance. It allows you to create, edit, and validate your OpenAPI specifications using multiple views that suit different user needs. Whether you prefer working directly with code, using a more interactive form layout, or reviewing the spec in a Swagger-like interface, ATA provides the tools to ensure your API is well-defined and compliant.

By leveraging error tracking and Spectral Rules, ATA helps ensure that your OpenAPI specs adhere to best practices, promoting security, consistency, and ease of integration.

Happy designing! 🚀

Create and Manage API ApplicationsGenerate Release Notes