Skip to content

docs: add tooling section #265

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
toumorokoshi merged 1 commit into from
Jan 13, 2025
Merged

docs: add tooling section #265

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions config/hero.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
54 changes: 54 additions & 0 deletions pages/general/tooling-and-ecosystem.md
View file
Open in desktop
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)"])
```
Loading