Skip to content

Commit 81e5d7c

Browse files
slashburyginslashburygin
authored
generate api_documentation.md (#330)
1 parent 53f04d2 commit 81e5d7c

6 files changed

Lines changed: 135 additions & 0 deletions

File tree

‎Makefile‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,6 @@ build_core:
1515

1616
bootstrap:
1717
exordos bootstrap -i output/inventory.json -f -m core --admin-password admin --cidr 10.20.0.0/22
18+
19+
mdlint:
20+
markdownlint-cli2 --config .markdownlint.yaml "**/*.md" "#node_modules" --fix

‎docs/em/api_documentation.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# API Documentation
2+
3+
## Resources
4+
5+
| Entity | Api | Manifest |
6+
|--------------------|----------------------------------------------------|--------------------------------|
7+
| MachinePool | /v1/compute/hypervisors/ | $core.compute.hypervisors |
8+
| Node | /v1/compute/nodes/ | $core.compute.nodes |
9+
| NodeSet | /v1/compute/sets/ | $core.compute.sets |
10+
| Volume | /v1/compute/volumes/ | $core.compute.volumes |
11+
| Config | /v1/config/configs/ | $core.config.configs |
12+
| Domain | /v1/dns/domains/ | $core.dns.domains |
13+
| Record | /v1/dns/domains/{DomainUuid}/records/ | $core.dns.domains.records |
14+
| Element | /v1/em/elements/ | $core.em.elements |
15+
| Export | /v1/em/elements/{ElementUuid}/exports/ | $core.em.elements.exports |
16+
| Import | /v1/em/elements/{ElementUuid}/imports/ | $core.em.elements.imports |
17+
| Resource | /v1/em/elements/{ElementUuid}/resources/ | $core.em.elements.resources |
18+
| Manifest | /v1/em/manifests/ | $core.em.manifests |
19+
| Service | /v1/em/services/ | $core.em.services |
20+
| IamClient | /v1/iam/clients/ | $core.iam.clients |
21+
| Idp | /v1/iam/idp/ | $core.iam.idp |
22+
| OrganizationMember | /v1/iam/organization_members/ | $core.iam.organization_members |
23+
| Organization | /v1/iam/organizations/ | $core.iam.organizations |
24+
| PermissionBinding | /v1/iam/permission_bindings/ | $core.iam.permission_bindings |
25+
| Permission | /v1/iam/permissions/ | $core.iam.permissions |
26+
| Project | /v1/iam/projects/ | $core.iam.projects |
27+
| RoleBinding | /v1/iam/role_bindings/ | $core.iam.role_bindings |
28+
| Role | /v1/iam/roles/ | $core.iam.roles |
29+
| User | /v1/iam/users/ | $core.iam.users |
30+
| LB | /v1/network/lb/ | $core.network.lb |
31+
| BackendPool | /v1/network/lb/{LBUuid}/backend_pools/ | $core.network.lb.backend_pools |
32+
| Vhost | /v1/network/lb/{LBUuid}/vhosts/ | $core.network.lb.vhosts |
33+
| Route | /v1/network/lb/{LBUuid}/vhosts/{VhostUuid}/routes/ | $core.network.lb.vhosts.routes |
34+
| Certificate | /v1/secret/certificates/ | $core.secret.certificates |
35+
| Password | /v1/secret/passwords/ | $core.secret.passwords |
36+
| RSAKey | /v1/secret/rsa_keys/ | $core.secret.rsa_keys |
37+
| SSHKey | /v1/secret/ssh_keys/ | $core.secret.ssh_keys |
38+
| Rule | /v1/security/rules/ | $core.security.rules |
39+
| Profile | /v1/vs/profiles/ | $core.vs.profiles |
40+
| Value | /v1/vs/values/ | $core.vs.values |
41+
| Variable | /v1/vs/variables/ | $core.vs.variables |

‎exordos_core/elements/dm/utils.py‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -241,6 +241,14 @@ def dump_full_manifest_schema(data):
241241
yaml.safe_dump(data, f)
242242

243243

244+
def dump_api_spec(data):
245+
with open(
246+
os.path.join(PROJECT_PATH, "docs", "em", "api_documentation.md"),
247+
"w",
248+
) as f:
249+
f.write(data)
250+
251+
244252
def load_user_api_spec() -> dict:
245253
with open(
246254
os.path.join(PROJECT_PATH, "docs", "openapi", "openapi_user.yaml"),
@@ -287,6 +295,7 @@ def build_full_schema(
287295
if not model:
288296
continue
289297
resource = f"$core.{api_parts}"
298+
model["path"] = path
290299
base_manifest_schema["components"]["schemas"][model_name] = model
291300
base_manifest_schema["properties"]["resources"]["properties"][
292301
resource
@@ -369,3 +378,42 @@ def mutate_manifest(manifest: dict, scheme: dict) -> dict:
369378
for resource_name, resource_value in resource.items():
370379
walk_replace(resource_type, scheme, resource_value)
371380
return manifest
381+
382+
383+
def extract_resources_for_markdown(full_schema):
384+
385+
resources_links = (
386+
full_schema.get("properties", {}).get("resources", {}).get("properties", {})
387+
)
388+
389+
resources = []
390+
391+
for resource_link_name, resource_ref in resources_links.items():
392+
ref = resource_ref.get("additionalProperties", {}).get("$ref")
393+
if not ref:
394+
continue
395+
resource_ref = ref.split("/")[-1]
396+
resource_schema = (
397+
full_schema.get("components", {}).get("schemas", {}).get(resource_ref)
398+
)
399+
if not resource_schema:
400+
continue
401+
resources.append(
402+
{
403+
"Entity": resource_ref.replace("_Create", ""),
404+
"Api": resource_schema.get("path"),
405+
"Manifest": resource_link_name,
406+
}
407+
)
408+
409+
return resources
410+
411+
412+
def generate_resources_markdown_table(resources):
413+
table = "| Entity | Api | Manifest |\n"
414+
table += "| ----- | --- | ------- |\n"
415+
for resource in resources:
416+
table += (
417+
f"| {resource['Entity']} | {resource['Api']} | {resource['Manifest']} |\n"
418+
)
419+
return table

‎exordos_core/tests/functional/manifests/test_validate.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,3 +109,10 @@ def test_validate_error(
109109
def test_build_full_schema(self, base_manifest_schema, user_api_spec):
110110
full_schema = utils.build_full_schema(base_manifest_schema, user_api_spec)
111111
utils.dump_full_manifest_schema(full_schema)
112+
113+
resources = utils.extract_resources_for_markdown(full_schema)
114+
content = "# API Documentation\n\n"
115+
content += "## Resources\n\n"
116+
content += utils.generate_resources_markdown_table(resources)
117+
content += "\n"
118+
utils.dump_api_spec(content)

0 commit comments

Comments
 (0)