-
Notifications
You must be signed in to change notification settings - Fork 15
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add a section that discusses the AEP tooling ecosystem. This will better improve the discoverability of the tools.
- Loading branch information
1 parent
f654697
commit 12584ef
Showing
1 changed file
with
54 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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)"]) | ||
``` |