diff --git a/config/hero.yaml b/config/hero.yaml index f2a2a73e..43cf8286 100644 --- a/config/hero.yaml +++ b/config/hero.yaml @@ -19,6 +19,14 @@ shortcuts: button: href: /contributing text: Contribute to the project + - title: Want to see the tools? + description: | + AEPs provide an ecosystem of tools to help produce compliant APIs and + interact with them. Learn more about how the tools fit in to a development + workflow. + button: + href: /general/tooling-and-ecosystem + text: View ecosystem - title: Want to adopt AEPs in your organization? description: | AEPs were adapted from [Google's AIP project](https://google.aip.dev/), but also enhanced with improved diff --git a/pages/general/tooling-and-ecosystem.md b/pages/general/tooling-and-ecosystem.md new file mode 100644 index 00000000..56ef91ba --- /dev/null +++ b/pages/general/tooling-and-ecosystem.md @@ -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(['aepc: service API generator']) + 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([aep-proto-linter: lint gRPC definitons for AEP compliance.]) + openapi --> http-generated{{api stubs via openapi-generator}} + openapi --> oas-linter([aep-openapi-linter: lint OAS definitions for AEP compliance.]) + 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([aepcli: a command-line interface for AEP-compliant APIs]) + http --> terraform_generator(["terraform provider generator (planned)"]) + terraform_generator --> terraform{{"terraform provider"}} + http --> llm[/"LLM plugin (external integration)"/] + http --> ui([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)"]) +```