Skip to content

Commit 5c1b424

Browse files
joelrosariojoelrosario
authored
Merge pull request #87
chore: update complete-examples section
2 parents 12e27ec + e40dcdd commit 5c1b424

File tree

3 files changed

+225
-131
lines changed

3 files changed

+225
-131
lines changed

‎docs/references/configuration/complete-examples.mdx‎

Lines changed: 59 additions & 131 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
title: Complete Examples
33
sidebar_position: 10
44
---
5+
import {JsonDisplay, YamlDisplay} from "../../../src/components/JsonYamlDisplay";
56
import Tabs from '@theme/Tabs';
67
import TabItem from '@theme/TabItem';
78

@@ -12,142 +13,69 @@ import TabItem from '@theme/TabItem';
1213

1314
This example shows all available configuration options:
1415

15-
<Tabs groupId="complete_configuration">
16-
17-
<TabItem value="specmatic-yaml" label="specmatic.yaml">
18-
19-
```yaml
20-
version: 2
21-
contracts:
22-
- git:
23-
url: https://azure.com/XNSio/XNSIO/_git/petstore-contracts
24-
branch: main
25-
provides:
26-
- com/petstore/store.yaml
27-
consumes:
28-
- com/petstore/payment.yaml
29-
30-
auth:
31-
bearer-file: central_repo_auth_token.txt
32-
33-
pipeline:
34-
provider: azure
35-
organization: XNSio
36-
project: XNSIO
37-
definitionId: 4
38-
39-
environments:
40-
staging:
41-
baseurls:
42-
auth.spec: http://localhost:8080
43-
variables:
44-
username: jackie
45-
password: PaSsWoRd
46-
47-
hooks:
48-
hook_name: command
49-
50-
report:
51-
formatters:
52-
- type: text
53-
layout: table
54-
types:
55-
APICoverage:
56-
OpenAPI:
57-
successCriteria:
58-
minThresholdPercentage: 100
59-
maxMissedEndpointsInSpec: 0
60-
enforce: true
61-
```
6216

63-
</TabItem>
64-
65-
<TabItem value="specmatic-json" label="specmatic.json">
66-
67-
```json
68-
{
69-
"version": 2,
70-
"contracts": [
71-
{
72-
"git": {
73-
"url": "https://azure.com/XNSio/XNSIO/_git/petstore-contracts",
74-
"branch": "main"
75-
},
76-
"provides": [
77-
"com/petstore/store.yaml"
78-
],
79-
"consumes": [
80-
"com/petstore/payment.yaml"
81-
]
82-
}
83-
],
84-
85-
"auth": {
86-
"bearer-file": "central_repo_auth_token.txt"
87-
},
88-
89-
"pipeline": {
90-
"provider": "azure",
91-
"organization": "XNSio",
92-
"project": "XNSIO",
93-
"definitionId": 4
94-
},
95-
96-
"environments": {
97-
"staging": {
98-
"baseurls": {
99-
"auth.spec": "http://localhost:8080"
100-
},
101-
"variables": {
102-
"username": "jackie",
103-
"password": "PaSsWoRd"
104-
}
105-
}
106-
},
107-
108-
"hooks": {
109-
"hook_name": "command"
110-
},
111-
112-
"report": {
113-
"formatters": [
114-
{
115-
"type": "text",
116-
"layout": "table"
117-
}
118-
],
119-
"types": {
120-
"APICoverage": {
121-
"OpenAPI": {
122-
"successCriteria": {
123-
"minThresholdPercentage": 100,
124-
"maxMissedEndpointsInSpec": 0,
125-
"enforce": true
126-
}
127-
}
128-
}
129-
}
130-
}
131-
}
132-
```
17+
<Tabs groupId={`tab-complete-examples`}>
18+
<TabItem value="v3" label="Version 3 (recommended)">
19+
<Tabs groupId="v3-tabs">
20+
<TabItem value={`specmatic-yaml-v3-complete-examples`} label="specmatic.yaml">
21+
<YamlDisplay object={require('./includes/complete-examples/v3/specmatic.json')}/>
22+
</TabItem>
23+
<TabItem value={`specmatic-json-v3-complete-examples`} label="specmatic.json">
24+
<JsonDisplay object={require('./includes/complete-examples/v3/specmatic.json')}/>
25+
</TabItem>
26+
</Tabs>
27+
28+
**Configuration Structure Summary (v3)**
29+
30+
The complete configuration file supports the following top-level sections:
31+
32+
1. **version** - Configuration version number (latest being `3`).
33+
2. **components** - Reusable components and definitions. Key sub-sections include:
34+
- `components.sources` - Define contract sources (Git repositories or filesystem locations) used to load API specs.
35+
- `components.services` - Service definitions referenced by `systemUnderTest` and `dependencies`. Each service
36+
typically contains `definitions` which reference a `source` and one or more `specs`.
37+
- `components.runOptions` - Named run configurations (for example, `openapi.type` = `test` or `mock`, and `baseUrl`)
38+
- `components.adapters` - Adapter definitions for massaging contract specifications, or for mutating request/responses
39+
from the proxy and/or stub.
40+
3. **systemUnderTest** - Defines the primary system under test. Contains a `components.service` entry and
41+
usually an associated `runOptions` profile for executing contract tests.
42+
4. **dependencies** - Defines dependent services used for service virtualization. Typically contains a `services`
43+
array where each item references a `components.services` entry and optional `runOptions` (often used to point to
44+
mock instances).
45+
5. **specmatic** - Specmatic-specific configuration:
46+
- `specmatic.settings` - Runtime and backward-compatibility settings (mock/test options, strictMode, baseBranch,
47+
delays, timeouts, etc.).
48+
- `specmatic.governance` - Reporting and success criteria (formats, outputDirectory, enforcement thresholds).
49+
- `specmatic.license` - License path or configuration.
50+
51+
For detailed information on each section, refer to the linked documentation pages.
13352

13453
</TabItem>
54+
<TabItem value="v2" label="Version 2">
55+
<Tabs groupId="v2-tabs">
56+
<TabItem value={`specmatic-yaml-v2-complete-examples`} label="specmatic.yaml">
57+
<YamlDisplay object={require('./includes/complete-examples/v2/specmatic.json')}/>
58+
</TabItem>
13559

136-
</Tabs>
60+
<TabItem value={`specmatic-json-v2-complete-examples`} label="specmatic.json">
61+
<JsonDisplay object={require('./includes/complete-examples/v2/specmatic.json')}/>
62+
</TabItem>
63+
</Tabs>
13764

138-
## Configuration Structure Summary
65+
**Configuration Structure Summary (v2)**
13966

140-
The complete configuration file supports the following top-level sections:
67+
The complete configuration file supports the following top-level sections:
14168

142-
1. **version** - Configuration version number (currently 2)
143-
2. **contracts** - Define API specifications from Git or filesystem
144-
3. **auth** - Authentication configuration for source control
145-
4. **pipeline** - CI/CD pipeline integration settings
146-
5. **environments** - Environment-specific variables and base URLs
147-
6. **hooks** - Custom commands for contract processing
148-
7. **test** - Contract testing configuration
149-
8. **stub** - Service virtualization configuration
150-
9. **report** - Report generation and formatting options
151-
10. **examples** - Directories for externalized examples
69+
1. **version** - Configuration version number (latest being `3`)
70+
2. [`contracts`](/references/configuration/contract-management) - Define API specifications from Git or filesystem
71+
3. [`hooks`](/references/configuration/hooks) - Custom commands for contract processing
72+
4. [`test`](/references/configuration/test-configuration) - Contract testing configuration
73+
5. [`mock`](/references/configuration/mock-configuration) - Service virtualization configuration
74+
6. [`report`](/references/configuration/reports) - Report generation and formatting options
75+
7. [`examples`](/references/configuration/mock-configuration#externalized-examples-directories) - Directories for
76+
externalized examples
15277

153-
For detailed information on each section, refer to the specific documentation pages.
78+
For detailed information on each section, refer to the specific documentation pages.
79+
80+
</TabItem>
81+
</Tabs>

‎docs/references/configuration/includes/complete-examples/v2/specmatic.json‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
{
2+
"version": 2,
3+
"contracts": [
4+
{
5+
"git": {
6+
"url": "https://github.com/specmatic/specmatic-order-contracts",
7+
"branch": "main"
8+
},
9+
"provides": [
10+
"com/petstore/store.yaml"
11+
],
12+
"consumes": [
13+
"com/petstore/payment.yaml"
14+
]
15+
}
16+
],
17+
"hooks": {
18+
"hook_name": "command"
19+
},
20+
"report": {
21+
"formatters": [
22+
{
23+
"type": "text",
24+
"layout": "table"
25+
},
26+
{
27+
"type": "html",
28+
"layout": "table"
29+
},
30+
{
31+
"type": "ctrf",
32+
"layout": "table"
33+
}
34+
],
35+
"types": {
36+
"APICoverage": {
37+
"OpenAPI": {
38+
"successCriteria": {
39+
"minThresholdPercentage": 100,
40+
"maxMissedEndpointsInSpec": 0,
41+
"enforce": true
42+
}
43+
}
44+
}
45+
}
46+
}
47+
}

‎docs/references/configuration/includes/complete-examples/v3/specmatic.json‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
{
2+
"version": 3,
3+
"systemUnderTest": {
4+
"service": {
5+
"$ref": "#/components/services/onlineStoreServiceV1",
6+
"runOptions": {
7+
"$ref": "#/components/runOptions/onlineStoreServiceV1Test"
8+
}
9+
}
10+
},
11+
"dependencies": {
12+
"services": [
13+
{
14+
"service": {
15+
"$ref": "#/components/services/orderServiceV1",
16+
"runOptions": {
17+
"$ref": "#/components/runOptions/orderServiceV1Mock"
18+
}
19+
}
20+
}
21+
]
22+
},
23+
"components": {
24+
"sources": {
25+
"centralContractRepo": {
26+
"git": {
27+
"url": "https://github.com/specmatic/specmatic-order-contracts.git"
28+
}
29+
}
30+
},
31+
"services": {
32+
"onlineStoreServiceV1": {
33+
"description": "Online Store Service (V1)",
34+
"definitions": [
35+
{
36+
"definition": {
37+
"source": {
38+
"$ref": "#/components/sources/centralContractRepo"
39+
},
40+
"specs": [
41+
"io/specmatic/examples/store/openapi/online_store_v1.yaml"
42+
]
43+
}
44+
}
45+
]
46+
},
47+
"orderServiceV1": {
48+
"description": "Payment Service (V1)",
49+
"definitions": [
50+
{
51+
"definition": {
52+
"source": {
53+
"$ref": "#/components/sources/centralContractRepo"
54+
},
55+
"specs": [
56+
"io/specmatic/examples/store/openapi/api_order_v1.yaml"
57+
]
58+
}
59+
}
60+
]
61+
}
62+
},
63+
"runOptions": {
64+
"onlineStoreServiceV1Test": {
65+
"openapi": {
66+
"type": "test",
67+
"baseUrl": "http://localhost:8080"
68+
}
69+
},
70+
"orderServiceV1Mock": {
71+
"openapi": {
72+
"type": "mock",
73+
"baseUrl": "http://localhost:8090"
74+
}
75+
}
76+
},
77+
"adapters": {
78+
"stub-hoks": {
79+
"test_load_contract": "python test_load_contract.py",
80+
"stub_load_contract": "python stub_load_contract.py",
81+
"post_specmatic_response_processor": "python post_specmatic_response_processor.py",
82+
"pre_specmatic_request_processor": "python pre_specmatic_request_processor.py",
83+
"pre_specmatic_response_processor": "python pre_specmatic_response_processor.py"
84+
}
85+
}
86+
},
87+
"specmatic": {
88+
"settings": {
89+
"backwardCompatibility": {
90+
"strictMode": true,
91+
"baseBranch": "origin/v3",
92+
"mock": {
93+
"delayInMilliseconds": 1000,
94+
"generative": true
95+
},
96+
"test": {
97+
"timeoutInMilliseconds": 1000
98+
}
99+
}
100+
},
101+
"governance": {
102+
"report": {
103+
"formats": [
104+
"ctrf",
105+
"html"
106+
],
107+
"outputDirectory": "reports/specmatic"
108+
},
109+
"successCriteria": {
110+
"enforce": true,
111+
"maxMissedOperationsInSpec": 10,
112+
"minCoveragePercentage": 75
113+
}
114+
},
115+
"license": {
116+
"path": "{LICENSE_PATH:/path/to/license/file-or-directory}"
117+
}
118+
}
119+
}

0 commit comments

Comments
 (0)