Auto OpenAPI Generation — The Network Doesn’t Lie!
Tags: api, openapi, java, tooling
Published: 2022-06-14 16:44:59

## API Visibility Is Key
Visibility of APIs is a fundamental necessity for governance, security, and productivity. Yet most organizations are unable to answer the following critical questions:

- What APIs do I have?
- Are [OpenAPI schemas](https://swagger.io/specification/) for the APIs documented and maintained?
- Which APIs process sensitive data?
- Which users access which APIs, under what roles (or scopes)?
- Which APIs are external vs. internal?

## Annotation Based OpenAPI Generation Is Not Scalable

### Disparate Set of Open Source Tools
There are a plethora of (language/framework specific) open source tools that generate OpenAPI specifications at build time, by scanning source code.

They use [code level annotations](https://en.wikipedia.org/wiki/Java_annotation) added by developers, to language/framework specific resources, methods, and controllers, to generate schema for APIs.

![Java Annotations for Swagger-Core](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/p8ih9gc776bf2m7e82bp.png)
<figcaption>
  <center>
    <a href="https://en.wikipedia.org/wiki/Java_annotation"> Java Annotations for Swagger-Core </a>
  </center>
</figcaption>
<br/>
Examples include [Swagger-Core](https://github.com/swagger-api/swagger-core), [SpringFox](https://github.com/springfox/springfox), [NSwag](https://github.com/RSuter/NSwag) / [Swashbuckle](https://github.com/domaindrivendev/Swashbuckle), [Swagger-express](https://github.com/fliptoo/swagger-express) / [HAPI-Swagger](https://github.com/glennjones/hapi-swagger), [Django-REST-Swagger](https://github.com/marcgibbons/django-rest-swagger) / [Flask-RESTplus](https://github.com/noirbizarre/flask-restplus), etc.

### These Tools Don’t Scale Well

![Polyglot Microservices](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ztfstebatihm0eyk0p4j.png)
<figcaption>
  <center>
    <p> Polyglot Microservices </p>
  </center>
</figcaption>

Modern development environments are polyglot in nature, where you find several small teams, using a variety of technology stacks, and disparate programming languages.

These tools don’t scale well in these environments due to the following reasons:

![Achieving Consistency Across Teams is Challenging](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/2g0u2kfcsy8l7cpeiah9.png)
<figcaption>
  <center>
    <p> Achieving Consistency Across Teams is Challenging </p>
  </center>
</figcaption>

- It is hard to achieve consistency (of API documentation) across so many small teams, disparate programming languages, and variety of language frameworks.
- Developers need to correctly annotate the code in appropriate places, lest the documentation will be incomplete and inaccurate.
- Developers need to maintain the annotations as they continuously refactor code, lest the documentation will be incomplete and inaccurate.
- Annotations are static in nature. When APIs return dynamic objects, the auto documented specification will be incorrect, or incomplete.
- There is no guarantee that what is auto documented, is the actual wire behavior exhibited by the API.

## The Network Doesn’t Lie
APIs transact by exchanging JSON data over the network. This makes the ***network***, the ***ultimate source of truth*** for API behavior, and schema.

Harnessing the network to auto discover & auto document APIs, in a *consistent* and *scalable* manner, has been challenging until recently.

## eBPF Based Automatic OpenAPI Generation

### Achieve Consistency & Scale, while Preserving Privacy
[eBPF](https://ebpf.io/) is revolutionary technology, that enables auto documentation of APIs in a consistent, scalable, and language/framework agnostic manner.

![Frictionless & Privacy-Preserving API observability](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/rolxbhvuwb6rbgsu1m8w.png)
<figcaption>
  <center>
    <a href="https://docs.levo.ai/beta/beta-features#frictionless-api-observability"> Frictionless & Privacy-Preserving API observability </a>
  </center>
</figcaption>
<br/>
[Levo](https://levo.ai/) provides a free service that automatically generates OpenAPI documentation for all your APIs, by [passively observing](https://docs.levo.ai/beta/api-observability/concepts#sensor) your runtime API traffic via eBPF.

The installation involves a single [Helm Chart](https://docs.levo.ai/beta/api-observability/quickstart) for Kubernetes, or a single [Docker command](https://docs.levo.ai/beta/api-observability/install-guide/install-sensor#install-on-linux-host-via-docker) for other environments. The installation does not require code changes, configuration changes, or SDK additions to your applications.

Ensuring the privacy of your customer data is paramount. You can read more about privacy-preserving features [here](https://docs.levo.ai/beta/api-observability/concepts#your-data-stays-with-you).

### Auto Generate OpenAPI with Sensitive Data Annotations
All APIs active in the runtime environments are auto discovered, and OpenAPI specifications are auto generated for them.


![Auto Discovered API Catalog](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/86moi1t67ug03pjpvbp5.png)
<figcaption>
  <center>
    <a href="https://docs.levo.ai/concepts/api-catalog"> Auto Discovered API Catalog </a>
  </center>
</figcaption>
<br/>
OpenAPI specifications are annotated with sensitive data types (PII, PSI, PHI, etc).


![Auto Generated OpenAPI Specifications](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/auwupnvlvzdtyaea88lu.png)
<figcaption>
  <center>
    <a href="https://docs.levo.ai/how-it-works#model"> Auto Generated OpenAPI Specifications </a>
  </center>
</figcaption>
<br/>
The API documentation is always fresh, and is based on the `single source of truth`, which is the actual API behavior observed on the network.

### Continuously Validate Existing OpenAPI Documentation
Teams building API documentation with an [API-First](https://swagger.io/resources/articles/adopting-an-api-first-approach/#:~:text=An%20API%2Dfirst%20approach%20means,be%20consumed%20by%20client%20applications.) approach, can also benefit.

Cross validate existing OpenAPI documentation with auto generated documentation for accuracy and completeness.

## Interested in trying Auto OpenAPI Generation?


![OpenAPI Auto Generation — Forever Free](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hubj0zbhjkujqjdnnhwt.png)
<figcaption>
  <center>
    <p> OpenAPI Auto Generation — Forever Free </p>
  </center>
</figcaption>

Levo is a [purpose-built](https://docs.levo.ai/how-it-works), developer-first API security solution that fully automates API Observability, API Documentation & API Testing in CI/CD pipelines.

[Signup](https://levo.ai/levo-signup/) for a forever free account, and start auto documenting all your APIs within minutes.

Have questions? Contact us at `info@levo.ai`.