{"id":29268968,"url":"https://github.com/specmatic/specmatic-arazzo-sample","last_synced_at":"2025-07-04T20:05:59.691Z","repository":{"id":302414158,"uuid":"938032483","full_name":"specmatic/specmatic-arazzo-sample","owner":"specmatic","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-02T08:17:44.000Z","size":32,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-07-02T09:30:00.117Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/specmatic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-02-24T10:10:23.000Z","updated_at":"2025-07-02T08:20:58.000Z","dependencies_parsed_at":"2025-07-02T09:31:27.794Z","dependency_job_id":"ac52af62-83ab-4258-ad91-e8a7c39cce75","html_url":"https://github.com/specmatic/specmatic-arazzo-sample","commit_stats":null,"previous_names":["znsio/specmatic-arazzo-sample"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/specmatic/specmatic-arazzo-sample","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/specmatic%2Fspecmatic-arazzo-sample","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/specmatic%2Fspecmatic-arazzo-sample/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/specmatic%2Fspecmatic-arazzo-sample/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/specmatic%2Fspecmatic-arazzo-sample/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/specmatic","download_url":"https://codeload.github.com/specmatic/specmatic-arazzo-sample/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/specmatic%2Fspecmatic-arazzo-sample/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263611899,"owners_count":23488428,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-04T20:05:52.392Z","updated_at":"2025-07-04T20:05:59.684Z","avatar_url":"https://github.com/specmatic.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Arazzo Sample Project\n\nThis project consists of three microservices:\n- **Order API**\n- **BFF (Backend for Frontend)**\n- **UUID API**\n\nAll services are developed using **FastAPI**, **SQLModel**, and **SQLite** as the database system.\n\n## Cloning the Repository\n\n1. Clone the repository\n```shell\ngit clone https://github.com/specmatic/specmatic-arazzo-sample.git\n```\n\n2. Initialize and update the specmatic-order-contracts submodule\n```shell\ngit submodule update --init --recursive --remote\n```\n\n3. Enable automatic submodule updating when executing git pull\n```shell\ngit config submodule.recurse true\n```\n\n## Setup Instructions\n\n### Setting Up Virtual Environment\n#### On Unix/macOS:\n```shell\npython3 -m venv venv\nsource venv/bin/activate\n```\n\n#### On Windows (Command Prompt):\n```shell\npython -m venv venv\nvenv\\Scripts\\activate\n```\n\n### Installing Dependencies\n```shell\npip install -r requirements.txt\n```\n\n## Service Interactions\nThe **[BFF](bff/)** service sends a request to the **[UUID API](uuid_api/)** to retrieve a UUID for a customer based on the request payload.\nIt subsequently uses this UUID to make a request to the **[Order API](order_api)**.\n\n### Running Contract Tests on the services that will be part of our workflow\n\nContract tests are run using `Specmatic` and `pytest`.\n\n- To run contract tests across all three services ([BFF](bff/), [UUID API](uuid_api/) and [Order API](order_api)):\n  ```shell\n  pytest -v -s\n  ```\n- To run tests for an individual service execute:\n  ```shell\n  pytest tests/\u003cservice_folder\u003e -v -s\n  ```\n\n## Authoring Arazzo Workflow Specification\n\nThe `workflow/` directory contains a [minimal Arazzo specification](workflow/uuid_order_workflow.arazzo.yaml) which only contains skeleton steps with references to `operations` (using `operationId`) from OpenAPI specifications of each of the services that are part of our workflow.\n\n### Extrapolating the Specification\n\nSpecmatic Arazzo can extrapolate a complete Arazzo specification based on the above minimal one by filling in missing parameters, request bodies, and defining success and failure actions and outputs.\nTo perform the extrapolation, execute:\n\n```shell\ndocker run --rm -v \"$(pwd):/usr/src/app\" specmatic/specmatic-arazzo extrapolate --spec-file=./workflow/uuid_order_workflow.arazzo.yaml -o ./workflow\n```\n\nAfter executing this command, you should see two new files generated in the [`workflow/`](workflow/) directory:\n\n1. **Extrapolated Specification:** [`uuid_order_workflow.arazzo_extrapolated.arazzo.yaml`](workflow/uuid_order_workflow.arazzo_extrapolated.arazzo.yaml)\n2. **Generated Inputs File:** [`uuid_order_workflow.arazzo_extrapolated.arazzo_input.json`](workflow/uuid_order_workflow.arazzo_extrapolated.arazzo_input.json)\n\n### Validating the Specification\n\nOnce the specification is extrapolated, validate it to ensure that all parameters, request bodies, schemas, outputs, and actions are correctly defined.\nRun the following command to validate the extrapolated specification:\n\n```shell\ndocker run --rm -v \"$(pwd):/usr/src/app\" specmatic/specmatic-arazzo validate --spec-file=./workflow/uuid_order_workflow.arazzo_extrapolated.arazzo.yaml\n```\n\n**Tip:** For testing purposes, consider removing the format of `email` field in the [extrapolated Arazzo API spec](workflow/uuid_order_workflow.arazzo_extrapolated.arazzo.yaml).\nThis alteration should trigger a validation failure (as shown below), demonstrating the effectiveness of the validation process.\n\n```shell\n\u003e\u003e ARAZZO-SPEC.WORKFLOW.PlaceOrder.STEP.GetUUID\n   In scenario \"Create a UUID. Response: Created\"\n   API: POST /uuids -\u003e 201\n     \u003e\u003e REQUEST.BODY.email\n        Expected email string, actual was string\n```\n\n### Running the Workflow\n\nBefore executing the workflow tests, verify that the input values in the [Arazzo inputs file](workflow/uuid_order_workflow.arazzo_extrapolated.arazzo_input.json) are in line with the seed data specified in `run.py`.\nThe `productId` in `PlaceOrder` and the `id` in `RetrieveProductDetails` should be set to either `1` or `2`.\n\n#### Initialize Services and Populate Data\nExecute the `run.py` script from the root directory to initialize the required services and populate the database with product data:\n\n```shell\npython run.py\n```\n\n#### Execute Workflow Tests\nAfter initializing the services, run the workflow tests using `Specmatic Arazzo`.\n\n```shell\ndocker run --rm -v \"$(pwd):/usr/src/app\" specmatic/specmatic-arazzo test --serverUrlIndex 1\n```\n\nUpon completion of the tests, a detailed HTML report will be generated in the [`build/reports/specmatic/html/index.html`](build/reports/specmatic/html/index.html) directory. \nThis report provides a comprehensive overview of the test outcomes, including a workflow diagram and additional information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspecmatic%2Fspecmatic-arazzo-sample","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspecmatic%2Fspecmatic-arazzo-sample","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspecmatic%2Fspecmatic-arazzo-sample/lists"}