We’re APIMatic.io. We generate strongly typed SDKs and complete API documentation from OpenAPI definitions. If you want to create an SDK for your REST API, check out how to generate one in under a minute. We support generating SDKs for C#, Java, PHP, TypeScript, Python, Ruby, and Go using the APIMatic Code Generator.

OpenAPI is one of the most widely used standards for defining HTTP APIs, but despite its popularity, we at APIMatic often encounter problematic OpenAPI definitions. These issues range from straightforward standard violations (think broken $refs) to problems that negatively affect SDK and documentation generation (think inline schemas, missing examples), ultimately hindering our users from fully benefiting from our Developer Experience solutions.

In fact, the challenge is significant enough: approximately 95% of the definitions we receive contain at least one issue. This might seem surprising, considering the number of validators and linters available to help users create valid OpenAPIs. However, merely being valid is often not enough, and the criteria for being valid can vary between tools.

Why are most OpenAPIs problematic?

In my opinion, the problems stem from the following reasons:

Your validator/linter tool choice influences your output

Different tools serve different purposes. As an example, validators like Swagger Editor can help you achieve standard compliance to a great deal but they won’t lint and catch issues related to security, documentation and code generation. Then there are linters like Spectral that give you great support for linting but are more lenient when enforcing standard compliance, allowing some issues to slip through. 

For obtaining an optimal OpenAPI definition, you may be better off using a combination of tools – though identifying the right combination isn’t always straightforward.

Hard to find a validator/linter focused on code generation

You’ll rarely come across validators or linters designed specifically for code generation that come with predefined rulesets, as this is a niche domain. While linters allow you to create custom rules based on your specific needs, the challenge lies in knowing exactly what to check for—something that’s not immediately obvious unless you're an expert in the field. 

As an example, a common issue we see in this area are inline schemas which are “anonymous”:

paths:
  /products/{id}:
    get:
      summary: Get a specific product by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: A single product object
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 1
                  name:
                    type: string
                    example: "Wireless Mouse"
                  price:
                    type: number
                    format: float
                    example: 29.99

While such schemas do not violate OpenAPI standards and are not flagged by tools, they can pose problems when code generation tools require unique names for schemas. Without these names, tools often auto-generate them, leading to code that is less user-friendly. A better approach would be to represent the schema with a unique identifier, such as “Product,” as shown below:

paths:
  /products/{id}:
    get:
      summary: Get a specific product by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: A single product object
          content:
            application/json:
              schema:
                $ref: ‘#/components/schemas/Product

Size of the API matters

The sheer size of the API and its definition can influence the number of issues found in an API definition document. For instance, if your API has more than 50 endpoints, you’re likely dealing with over 500 schemas, give or take. This could easily result in an API definition encompassing several thousand lines. Ensuring that every parameter and schema has proper descriptions and examples to generate user-friendly documentation easily becomes a substantial task.

Auto-generated OpenAPIs can lack metadata

OpenAPIs are often auto-generated from annotated code, as is the case with Swashbuckle for .NET. You can easily generate a valid OpenAPI file with only basic annotations. However, a basic OpenAPI file isn't necessarily complete; for example, it may lack detailed descriptions and examples unless you choose to add that information yourself.

Why Should I Care?

Your API definition is a critical piece of your whole Developer Experience program. Here are a few reasons why it matters:

• Ease of integration: The quality of your API definition directly influences the quality of generated artifacts like SDKs and documentation. Well-crafted SDKs and documentation in turn can greatly reduce integration time for your end-users. In today’s era, such API definitions can also help power AI assistants that can further expedite integration tasks and support the development of applications that drive market success.
• Compatibility with tools: A standards-compliant API definition will work seamlessly with all kinds of API tools, giving you access to a broader ecosystem.
• Increased Usability and API Adoption: A user-focused API definition with plenty of examples and clear descriptions results in documentation that is much easier for your end-users to understand and work with when integrating with your API.
• Faster time to market: If you are careful and consistent with your naming conventions, your development process will be less error prone and save valuable time.

So, What Should I Do?

If you are an API provider looking to auto-generate SDKs or documentation from your API definitions, it is important to first assess how good/bad your API definitions currently are, identify which areas need most improvement, plan accordingly and then take action to address the identified issues. Once you’re confident in the quality of your API definitions, it’s time to generate and enjoy the results!

APIMatic has recently launched two products Score My OpenAPI and Fix My OpenAPI to help streamline your whole API definitions improvement process described above.

Step 1: Assess Your API Definition with Score My OpenAPI

Head over to Score My OpenAPI to quickly receive a free audit report for your API definitions, delivered directly to your inbox:

The report will highlight:

• The overall score for your API definition out of 100. Anything below 50 means trouble while anything below 90 can imply some compromise on the quality of output you can get from your API definition. This, along with the total number of issues identified, will give you a better idea of how much work your API definition still needs.

• Additional statistics that show the most affected areas, so you can prioritize accordingly.
• A bird’s eye view of all issues:

  

• Details for each specific issue including a description, actionable hints and external links to help you fix the problem, along with a list of affected components with precise file and line locations.

Step 2: Debug your OpenAPI with Fix My OpenAPI

After identifying the issues, the next step is to work on eliminating them. If there are too many issues, the task can quickly become overwhelming. Keeping that in mind, we created  Fix My OpenAPI, a VS Code extension tool that comes bundled with over 1200+ rules to help you fix everything – from standard compliance issues to those related to code generation and documentation. It will not only allow you to edit and fix your API definitions in a familiar environment but also helps speed up the process with advanced features like auto-fixing. 

The extension includes dedicated views to help you quickly navigate through issues, prioritize them based on your needs, and resolve them using embedded help content, also within the extension.

As you make progress, the extension will update your score in real-time. You can even generate subsequent audit reports to share with stakeholders, if needed.

You can download the extension from VS Marketplace here.

Step 3. Repeat 1 and 2

Continue assessing and optimizing your API definitions until you are satisfied with their score and overall quality. Once you're confident, you're ready to move to the next step.

Next Steps: Auto-generate a Developer Experience Kit 🎉

If you’ve managed to get a good score and gain more confidence on your API definitions quality, congratulations! You are all set for the next step: auto-generation of a complete Developer Experience package with APIMatic. This package includes SDKs in multiple languages, documentation with a try-it-out console, dynamic code samples as well as an API Copilot to further streamline your process. 

Sign up for APIMatic today and get started!

Conclusion

A well defined API definition goes hand in hand with a great developer experience. Optimize your API definitions with APIMatic to auto-generate high quality SDKs and Developer Experience portals with cutting-edge AI technology. This approach will not only reduce your time to market but also increase API adoption rates.