Skip to content

Commit

Permalink
docs: add tooling section
Browse files Browse the repository at this point in the history
Add a section that discusses the AEP tooling ecosystem. This
will better improve the discoverability of the tools.
  • Loading branch information
toumorokoshi committed Jan 11, 2025
1 parent f654697 commit 12584ef
Showing 1 changed file with 54 additions and 0 deletions.
54 changes: 54 additions & 0 deletions pages/general/tooling-and-ecosystem.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# Tooling and Ecosystem

In addition to an API design specification, AEPs also provide an ecosystem of
tooling to help produce and interact with these APIs.

## Diagram

The following is a diagram that illustrates an end-to-end workflow, including
nodes of tooling that exists, or is intended to be created for the project.

Some of the tools in the diagram are not maintained by the AEP project. The
diagram is intended to be a complete representation of tools available to help
a user understand how the tools fit in to a development workflow.

```mermaid
flowchart TD
tool([tool])
use-case[/possible use case/]
user(user authored)
generated{{generated}}
```

The service generation tooling looks like:

```mermaid
flowchart TD
resources("AEP Resource yaml")
resources --> hub(['<a href="https://github.com/aep-dev/aepc">aepc: service API generator</a>'])
hub --> proto{{"gRPC protobuf definition"}}
hub --> openapi{{"OpenAPI Schema"}}
hub --> graphql[/GraphQL definitions/]
proto --> proto-service(your proto service)
proto-service --> http-grpc{{"HTTP REST APIs via grpc-gateway"}}
proto --> proto-linter([<a href="https://github.com/aep-dev/api-linter">aep-proto-linter: lint gRPC definitons for AEP compliance.</a>])
openapi --> http-generated{{api stubs via openapi-generator}}
openapi --> oas-linter([<a href="https://github.com/aep-dev/aep-openapi-linter">aep-openapi-linter: lint OAS definitions for AEP compliance.</a>])
http-generated --> http-service(your http service)
```

While the client tooling for an AEP-compliant compatible API includes:

```mermaid
flowchart LR
http["AEP-compliant REST API and OpenAPI definition"]
http --> cli([<a href="https://github.com/aep-dev/aepcli">aepcli: a command-line interface for AEP-compliant APIs</a>])
http --> terraform_generator(["terraform provider generator (planned)"])
terraform_generator --> terraform{{"terraform provider"}}
http --> llm[/"LLM plugin (external integration)"/]
http --> ui([<a href="https://github.com/aep-dev/aep-explorer">aep-explorer: interactive web UI to create, edit, list, and modify resources])
http --> sdks[/"Language-specific libraries (e.g. via openapi-generator)"/]
http --> asset_inventory[/"Asset inventory and policy management tooling (external integration)"/]
http --> crd_generator(["Kubernetes Custom Resource Definitions generator"])
http --> docs(["API documentation generator (planned)"])
```

0 comments on commit 12584ef

Please sign in to comment.