feat: updated existing APIs to enable to generate OpenAPI documentation

backend/editor/api.py

@@ -28,16 +28,14 @@
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import FileResponse, JSONResponse
 
+# Data model imports
 # DB helper imports
-from . import graph_db
+from . import graph_db, models
 from .entries import TaxonomyGraph
 
 # Custom exceptions
 from .exceptions import GithubBranchExistsError, GithubUploadError
 
-# Data model imports
-from .models import Footer, Header
-
 # -----------------------------------------------------------------------------------#
 
 # Setup logs
@@ -360,15 +358,22 @@ async def export_to_github(
 # Post methods
 
 
-@app.post("/{taxonomy_name}/{branch}/import")
-async def import_from_github(request: Request, branch: str, taxonomy_name: str):
+@app.post("/{taxonomy_name}/{branch}/import", response_model=models.ImportFromGithubResponse)
+async def import_from_github(
+    request: Request,
+    parameters: models.ImportFromGithubParameters,
+):
     """
     Get taxonomy from Product Opener GitHub repository
+
+    - **branch**: name of branch added by user
+    - **taxonomy**: name of the taxonomy added by user
+
     """
     incoming_data = await request.json()
     description = incoming_data["description"]
 
-    taxonomy = TaxonomyGraph(branch, taxonomy_name)
+    taxonomy = TaxonomyGraph(parameters.branch, parameters.taxonomy_name)
     if not taxonomy.is_valid_branch_name():
         raise HTTPException(status_code=400, detail="branch_name: Enter a valid branch name!")
     if await taxonomy.does_project_exist():
@@ -406,11 +411,11 @@ async def upload_taxonomy(
 
 
 @app.post("/{taxonomy_name}/{branch}/nodes")
-async def create_node(request: Request, branch: str, taxonomy_name: str):
+async def create_node(request: Request, parameters: models.CreateNodeParameters):
     """
     Creating a new node in a taxonomy
     """
-    taxonomy = TaxonomyGraph(branch, taxonomy_name)
+    taxonomy = TaxonomyGraph(parameters.branch, parameters.taxonomy_name)
     incoming_data = await request.json()
     id = incoming_data["id"]
     main_language = incoming_data["main_language"]
@@ -427,42 +432,44 @@ async def create_node(request: Request, branch: str, taxonomy_name: str):
         await taxonomy.add_node_to_beginning(label, normalized_id)
 
 
-@app.post("/{taxonomy_name}/{branch}/entry/{entry}")
-async def edit_entry(request: Request, branch: str, taxonomy_name: str, entry: str):
+@app.post("/{taxonomy_name}/{branch}/entry/{entry}", response_model=models.EditEntryResponse)
+async def edit_entry(request: Request, parameters: models.EditEntryParameters):
     """
     Editing an entry in a taxonomy.
     New key-value pairs can be added, old key-value pairs can be updated.
     URL will be of format '/entry/<id>'
     """
-    taxonomy = TaxonomyGraph(branch, taxonomy_name)
+    taxonomy = TaxonomyGraph(parameters.branch, parameters.taxonomy_name)
     incoming_data = await request.json()
-    updated_entry = await taxonomy.update_nodes("ENTRY", entry, incoming_data)
+    updated_entry = await taxonomy.update_nodes("ENTRY", parameters.entry, incoming_data)
     return updated_entry
 
 
-@app.post("/{taxonomy_name}/{branch}/entry/{entry}/children")
-async def edit_entry_children(request: Request, branch: str, taxonomy_name: str, entry: str):
+@app.post(
+    "/{taxonomy_name}/{branch}/entry/{entry}/children", response_model=models.EditChildrenResponse
+)
+async def edit_entry_children(request: Request, parameters: models.EditChildrenParameters):
     """
     Editing an entry's children in a taxonomy.
     New children can be added, old children can be removed.
     URL will be of format '/entry/<id>/children'
     """
-    taxonomy = TaxonomyGraph(branch, taxonomy_name)
+    taxonomy = TaxonomyGraph(parameters.branch, parameters.taxonomy_name)
     incoming_data = await request.json()
-    updated_children = await taxonomy.update_node_children(entry, incoming_data)
+    updated_children = await taxonomy.update_node_children(parameters.entry, incoming_data)
     return updated_children
 
 
-@app.post("/{taxonomy_name}/{branch}/synonym/{synonym}")
-async def edit_synonyms(request: Request, branch: str, taxonomy_name: str, synonym: str):
+@app.post("/{taxonomy_name}/{branch}/synonym/{synonym}", response_model=models.EditSynonymResponse)
+async def edit_synonyms(request: Request, parameters: models.EditSynonymParameters):
     """
     Editing a synonym in a taxonomy.
     New key-value pairs can be added, old key-value pairs can be updated.
     URL will be of format '/synonym/<id>'
     """
-    taxonomy = TaxonomyGraph(branch, taxonomy_name)
+    taxonomy = TaxonomyGraph(parameters.branch, parameters.taxonomy_name)
     incoming_data = await request.json()
-    updated_synonym = await taxonomy.update_nodes("SYNONYMS", synonym, incoming_data)
+    updated_synonym = await taxonomy.update_nodes("SYNONYMS", parameters.synonym, incoming_data)
     return updated_synonym
 
 
@@ -479,24 +486,25 @@ async def edit_stopwords(request: Request, branch: str, taxonomy_name: str, stop
     return updated_stopword
 
 
-@app.post("/{taxonomy_name}/{branch}/header")
-async def edit_header(incoming_data: Header, branch: str, taxonomy_name: str):
+@app.post("/{taxonomy_name}/{branch}/header", response_model=models.EditHeaderResponse)
+async def edit_header(parameters: models.EditHeaderParameters):
     """
     Editing the __header__ in a taxonomy.
     """
-    taxonomy = TaxonomyGraph(branch, taxonomy_name)
-    convertedData = incoming_data.dict()
+    taxonomy = TaxonomyGraph(parameters.branch, parameters.taxonomy_name)
+    convertedData = parameters.incoming_data.dict()
+
     updated_header = await taxonomy.update_nodes("TEXT", "__header__", convertedData)
     return updated_header
 
 
-@app.post("/{taxonomy_name}/{branch}/footer")
-async def edit_footer(incoming_data: Footer, branch: str, taxonomy_name: str):
+@app.post("/{taxonomy_name}/{branch}/footer", response_model=models.EditFooterResponse)
+async def edit_footer(parameters: models.EditFooterParameters):
     """
     Editing the __footer__ in a taxonomy.
     """
-    taxonomy = TaxonomyGraph(branch, taxonomy_name)
-    convertedData = incoming_data.dict()
+    taxonomy = TaxonomyGraph(parameters.branch, parameters.taxonomy_name)
+    convertedData = parameters.incoming_data.dict()
     updated_footer = await taxonomy.update_nodes("TEXT", "__footer__", convertedData)
     return updated_footer
 

backend/editor/models.py

@@ -3,11 +3,14 @@
 """
 from typing import List
 
-from pydantic import BaseModel
+from fastapi import Query
+from pydantic import BaseConfig, BaseModel
+
+BaseConfig.arbitrary_types_allowed = True
 
 
 class Marginal(BaseModel):
-    preceding_lines: List
+    preceding_lines: List = Query(description="A list of preceding lines")
 
 
 class Header(Marginal):
@@ -16,3 +19,65 @@ class Header(Marginal):
 
 class Footer(Marginal):
     pass
+
+
+class CommonParameters(BaseModel):
+    branch: str = Query(description="Name of the branch")
+    taxonomy_name: str = Query(description="Name of the taxonomy")
+
+
+class Entry(CommonParameters):
+    entry: str = Query(description="Name of the entry")
+    id: str = Query(description="Id of the entry")
+
+
+class ImportFromGithubParameters(CommonParameters):
+    pass
+
+
+class ImportFromGithubResponse(BaseModel):
+    status: bool = Query(description="True if import was successful")
+
+
+class CreateNodeParameters(CommonParameters):
+    pass
+
+
+class EditEntryParameters(CommonParameters):
+    entry: str = Query(description="Name of the entry")
+
+
+class EditEntryResponse(BaseModel):
+    result: List[Entry]
+
+
+class EditChildrenParameters(CommonParameters):
+    entry: str = Query(description="Name of the entry")
+
+
+class EditChildrenResponse(BaseModel):
+    result: List
+
+
+class EditSynonymParameters(CommonParameters):
+    entry: str = Query(description="Name of the entry")
+
+
+class EditSynonymResponse(BaseModel):
+    result: List
+
+
+class EditHeaderParameters(CommonParameters):
+    incoming_data: Header
+
+
+class EditHeaderResponse(BaseModel):
+    result: dict
+
+
+class EditFooterParameters(CommonParameters):
+    incoming_data: Footer
+
+
+class EditFooterResponse(BaseModel):
+    result: dict

taxonomy-editor-frontend/build/.empty

@@ -1,2 +1 @@
-# keep this folder to avoid having docker-compose create it with root owner
-
+# keep this file to have the folder in git to avoid permissions problem (if docker-compose creates the build directory, it will be owned by root