Function document_api

scripts/describe.py:394–460

Document the given API. Args: name (str): Name of the API. version (str): Version of the API. uri (str): URI of the API's discovery document doc_destination_dir (str): relative path where the reference documentation should be saved. artifact_d

(
    name,
    version,
    uri,
    doc_destination_dir,
    artifact_destination_dir=DISCOVERY_DOC_DIR,
)

def document_api(
    name,
    version,
    uri,
    doc_destination_dir,
    artifact_destination_dir=DISCOVERY_DOC_DIR,
):
    """Document the given API.

    Args:
        name (str): Name of the API.
        version (str): Version of the API.
        uri (str): URI of the API's discovery document
        doc_destination_dir (str): relative path where the reference
            documentation should be saved.
        artifact_destination_dir (Optional[str]): relative path where the discovery
            artifacts should be saved.
    """
    http = build_http()
    resp, content = http.request(uri)

    if resp.status == 200:
        discovery = json.loads(content)
        service = build_from_document(discovery)
        doc_name = "{}.{}.json".format(name, version)
        discovery_file_path = artifact_destination_dir / doc_name
        revision = None

        pathlib.Path(discovery_file_path).touch(exist_ok=True)

        # Write discovery artifact to disk if revision equal or newer
        with open(discovery_file_path, "r+") as f:
            try:
                json_data = json.load(f)
                revision = json_data["revision"]
            except json.JSONDecodeError:
                revision = None

            if revision is None or discovery["revision"] >= revision:
                # Reset position to the beginning
                f.seek(0)
                # Write the changes to disk
                json.dump(discovery, f, indent=0, sort_keys=True)
                # Truncate anything left as it's not needed
                f.truncate()

    elif resp.status == 404:
        print(
            "Warning: {} {} not found. HTTP Code: {}".format(name, version, resp.status)
        )
        return
    else:
        print(
            "Warning: {} {} could not be built. HTTP Code: {}".format(
                name, version, resp.status
            )
        )
        return