docs(robot-server): Audit HTTP API documentation (#14294)

Author: SyntaxColoring

robot-server/robot_server/app_setup.py

@@ -54,6 +54,9 @@
     ),
     version=__version__,
     exception_handlers=exception_handlers,
+    # Disable documentation hosting via Swagger UI, normally at /docs.
+    # We instead focus on the docs hosted by ReDoc, at /redoc.
+    docs_url=None,
 )
 
 # cors

robot-server/robot_server/deck_configuration/models.py

@@ -39,15 +39,21 @@ class DeckConfigurationRequest(pydantic.BaseModel):
     """A request to set the robot's deck configuration."""
 
     cutoutFixtures: List[CutoutFixture] = pydantic.Field(
-        description="A full list of all the cutout fixtures that are mounted onto the deck."
+        description=(
+            "A full list of all the cutout fixtures that are mounted onto the deck."
+            " The order is arbitrary."
+        )
     )
 
 
 class DeckConfigurationResponse(pydantic.BaseModel):
     """A response for the robot's current deck configuration."""
 
     cutoutFixtures: List[CutoutFixture] = pydantic.Field(
-        description="A full list of all the cutout fixtures that are mounted onto the deck."
+        description=(
+            "A full list of all the cutout fixtures that are mounted onto the deck."
+            " The order is arbitrary."
+        )
     )
     lastModifiedAt: Optional[datetime] = pydantic.Field(
         description=(

robot-server/robot_server/deck_configuration/router.py

@@ -27,7 +27,7 @@
 @PydanticResponse.wrap_route(
     router.put,
     path="/deck_configuration",
-    summary="Set the deck configuration",
+    summary="Set the Flex deck configuration",
     description=(
         "Inform the robot how its deck is physically set up."
         "\n\n"
@@ -38,15 +38,18 @@
         " configuration, such as loading a labware into a staging area slot that this deck"
         " configuration doesn't provide, the run command will fail with an error."
         "\n\n"
+        "After you set the deck configuration, it will persist, even across reboots,"
+        " until you set it to something else."
+        "\n\n"
         "**Warning:**"
         " Currently, you can call this endpoint at any time, even while there is an active run."
         " However, the robot can't adapt to deck configuration changes in the middle of a run."
         " The robot will effectively take a snapshot of the deck configuration when the run is"
         " first played. In the future, this endpoint may error if you try to call it in the middle"
         " of an active run, so don't rely on being able to do that."
         "\n\n"
-        "After you set the deck configuration, it will persist, even across reboots,"
-        " until you set it to something else."
+        "**Warning:** Only use this on Flex robots, never OT-2 robots. The behavior on"
+        " OT-2 robots is currently undefined and it may interfere with protocol execution."
     ),
     responses={
         fastapi.status.HTTP_200_OK: {
@@ -86,10 +89,13 @@ async def put_deck_configuration(  # noqa: D103
 @PydanticResponse.wrap_route(
     router.get,
     path="/deck_configuration",
-    summary="Get the deck configuration",
+    summary="Get the Flex deck configuration",
     description=(
         "Get the robot's current deck configuration."
         " See `PUT /deck_configuration` for background information."
+        "\n\n"
+        "**Warning:** The behavior of this endpoint is currently only defined for Flex"
+        " robots, not OT-2 robots."
     ),
     responses={
         fastapi.status.HTTP_200_OK: {

robot-server/robot_server/instruments/router.py

@@ -254,9 +254,14 @@ async def _get_attached_instruments_ot2(
 @PydanticResponse.wrap_route(
     instruments_router.get,
     path="/instruments",
-    summary="Get attached instruments.",
-    description="Get a list of all instruments (pipettes & gripper) currently attached"
-    " to the robot.",
+    summary="Get attached instruments",
+    description=(
+        "Get a list of all instruments (pipettes & gripper) currently attached"
+        " to the robot."
+        "\n\n"
+        "**Warning:** The behavior of this endpoint is currently only defined for Flex"
+        " robots. For OT-2 robots, use `/pipettes` instead."
+    ),
     responses={status.HTTP_200_OK: {"model": SimpleMultiBody[AttachedItem]}},
 )
 async def get_attached_instruments(

robot-server/robot_server/protocols/protocol_models.py

@@ -102,4 +102,10 @@ class Protocol(ResourceModel):
         ),
     )
 
-    key: Optional[str] = None
+    key: Optional[str] = Field(
+        None,
+        description=(
+            "An arbitrary client-defined string, set when this protocol was uploaded."
+            " See `POST /protocols`."
+        ),
+    )

robot-server/robot_server/protocols/router.py

@@ -19,6 +19,7 @@
     FileHasher,
 )
 from opentrons_shared_data.robot.dev_types import RobotType
+
 from robot_server.errors.error_responses import ErrorDetails, ErrorBody
 from robot_server.hardware import get_robot_type
 from robot_server.service.task_runner import TaskRunner, get_task_runner
@@ -154,7 +155,16 @@ async def create_protocol(
     files: List[UploadFile] = File(...),
     # use Form because request is multipart/form-data
     # https://fastapi.tiangolo.com/tutorial/request-forms-and-files/
-    key: Optional[str] = Form(None),
+    key: Optional[str] = Form(
+        default=None,
+        description=(
+            "An arbitrary client-defined string to attach to the new protocol resource."
+            " This should be no longer than ~100 characters or so."
+            " It's intended to store something like a UUID, to help clients that store"
+            " protocols locally keep track of which local files correspond to which"
+            " protocol resources on the robot."
+        ),
+    ),
     protocol_directory: Path = Depends(get_protocol_directory),
     protocol_store: ProtocolStore = Depends(get_protocol_store),
     analysis_store: AnalysisStore = Depends(get_analysis_store),

robot-server/robot_server/router.py

@@ -72,7 +72,7 @@
 
 router.include_router(
     router=deck_configuration_router,
-    tags=["Deck Configuration"],
+    tags=["Flex Deck Configuration"],
     dependencies=[Depends(check_version_header)],
 )
 
@@ -90,7 +90,7 @@
 
 router.include_router(
     router=deprecated_session_router,
-    tags=["Session Management"],
+    tags=["OT-2 Calibration Sessions"],
     dependencies=[Depends(check_version_header)],
 )
 
@@ -120,7 +120,7 @@
 
 router.include_router(
     router=subsystems_router,
-    tags=["Subsystem Management"],
+    tags=["Flex Subsystem Management"],
     dependencies=[Depends(check_version_header)],
 )
 

robot-server/robot_server/service/json_api/response.py

@@ -110,7 +110,7 @@ class SimpleMultiBody(BaseResponseBody, GenericModel, Generic[ResponseDataT]):
     # to be covariant is to make data the covariant Sequence protocol.
     meta: MultiBodyMeta = Field(
         ...,
-        description="Metadata about the colletion response.",
+        description="Metadata about the collection response.",
     )
 
 
@@ -125,7 +125,7 @@ class MultiBody(
     links: ResponseLinksT = Field(..., description=DESCRIPTION_LINKS)
     meta: MultiBodyMeta = Field(
         ...,
-        description="Metadata about the colletion response.",
+        description="Metadata about the collection response.",
     )
 
 

robot-server/robot_server/service/labware/router.py

@@ -36,6 +36,7 @@ class LabwareCalibrationEndpointsRemoved(ErrorDetails):
         "This endpoint has been removed."
         " Use the `/runs` endpoints to manage labware offsets."
     ),
+    deprecated=True,
     response_model=None,
     responses={
         status.HTTP_200_OK: {"model": lw_models.MultipleCalibrationsResponse},
@@ -62,6 +63,7 @@ async def get_all_labware_calibrations(
         "This endpoint has been removed."
         " Use the `/runs` endpoints to manage labware offsets."
     ),
+    deprecated=True,
     response_model=None,
     responses={
         status.HTTP_404_NOT_FOUND: {"model": ErrorBody},
@@ -89,6 +91,7 @@ async def get_specific_labware_calibration(
         "This endpoint has been removed."
         " Use the `/runs` endpoints to manage labware offsets."
     ),
+    deprecated=True,
     response_model=None,
     responses={
         status.HTTP_404_NOT_FOUND: {"model": ErrorBody},

robot-server/robot_server/service/legacy/models/deck_calibration.py

@@ -29,8 +29,22 @@
 
 
 class InstrumentOffset(BaseModel):
-    single: Offset
-    multi: Offset
+    single: Offset = Field(
+        ...,
+        deprecated=True,
+        description=(
+            "This will always be `[0, 0, 0]`."
+            " Use the `GET /calibration/pipette_offset` endpoint instead."
+        ),
+    )
+    multi: Offset = Field(
+        ...,
+        deprecated=True,
+        description=(
+            "This will always be `[0, 0, 0]`."
+            " Use the `GET /calibration/pipette_offset` endpoint instead."
+        ),
+    )
 
 
 class InstrumentCalibrationStatus(BaseModel):
@@ -59,7 +73,12 @@ class DeckCalibrationData(BaseModel):
         None, description="The ID of the pipette used in this calibration"
     )
     tiprack: typing.Optional[str] = Field(
-        None, description="The sha256 hash of the tiprack used in this calibration"
+        None,
+        description="A hash of the labware definition of the tip rack that"
+        " was used in this calibration."
+        " This is deprecated because it was prone to bugs where semantically identical"
+        " definitions had different hashes.",
+        deprecated=True,
     )
     source: typing.Optional[SourceType] = Field(
         None, description="The calibration source"