You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: _includes/setup_command_line.md
+2-2Lines changed: 2 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -10,13 +10,13 @@ The Specmatic standalone executable is accessible through various prominent dist
10
10
You can run Specmatic using the following command:
11
11
12
12
```bash
13
-
docker run znsio/specmatic
13
+
docker run specmatic/specmatic
14
14
```
15
15
16
16
{% endtab %}
17
17
18
18
{% tab install java %}
19
-
Download the standalone jar from our [Github releases](<https://github.com/znsio/specmatic/releases/download/{{ site.latest_release }}/specmatic.jar>) or [Maven Central](https://repo1.maven.org/maven2/io/specmatic/specmatic-executable-all/{{ site.latest_release }}/specmatic-executable-all-{{ site.latest_release }}.jar).
19
+
Download the standalone jar from our [Github releases](<https://github.com/specmatic/specmatic/releases/download/{{ site.latest_release }}/specmatic.jar>) or [Maven Central](https://repo1.maven.org/maven2/io/specmatic/specmatic-executable-all/{{ site.latest_release }}/specmatic-executable-all-{{ site.latest_release }}.jar).
20
20
21
21
If you have downloaded the standalone jar from Maven Central, you may want to rename it as shown below for convenience.
Place this file in the root folder of your project (Here is an [example](https://github.com/znsio/specmatic-order-api-java)). Let us now go through each of the lines in this file.
112
+
Place this file in the root folder of your project (Here is an [example](https://github.com/specmatic/specmatic-order-api-java)). Let us now go through each of the lines in this file.
113
113
* **provider** - At the moment we support all git based source control systems. Example: GitHub, Gitlab, Azure, etc.
114
114
* **repository** - The git repository URL
115
115
* **provides** - This is the list of API Specifications that need to be run as a test. Note that the path is relative to the source control repository root.
@@ -123,7 +123,7 @@ You can also specify the branch.
Please note that now we are now listing the ```api_order_v3.yaml``` is listed as a stub dependency. You can run the ```specmatic stub``` command and the Specmatic will clone the API specifications and run it as a stub. Here is an [example](https://github.com/znsio/specmatic-order-bff-java/blob/main/specmatic.yaml).
275
+
Please note that now we are now listing the ```api_order_v3.yaml``` is listed as a stub dependency. You can run the ```specmatic stub``` command and the Specmatic will clone the API specifications and run it as a stub. Here is an [example](https://github.com/specmatic/specmatic-order-bff-java/blob/main/specmatic.yaml).
276
276
277
277
A single application may need to list the API Specifications it is implementing under the provides attribute and the API Specifications of its dependencies under the consumes attribute.
278
278
@@ -393,7 +393,7 @@ Note that the `consumes` and `provides` can both contain URLs. `http` and `https
393
393
394
394
Usually source control requires authentication. Below are the ways in which you can set it up.
395
395
* Recommended approach - Provide a Git SSH URL and make sure your environment already has necessary keys loaded. If the git clone command works on your regular command line, it will work within Specmatic too. This is most suitable in CI, because your CI server may already be setup to clone the application code (for which the CI server should already have the necessary keys). So it should already be able to clone your API Specifications also. The same also should be applicable for local development and testing environments.
396
-
* Alternatives - With https URLs you can provide the bearer token or other means. Please reach us (raise a [github issue](https://github.com/znsio/specmatic/issues/new/choose)) if you need help with this.
396
+
* Alternatives - With https URLs you can provide the bearer token or other means. Please reach us (raise a [github issue](https://github.com/specmatic/specmatic/issues/new/choose)) if you need help with this.
397
397
398
398
#### Report Configuration
399
399
Specmatic can generate reports based on the below configuration:
Copy file name to clipboardExpand all lines: documentation/authentication-by-reaching-another-service.md
+6-6Lines changed: 6 additions & 6 deletions
Original file line number
Diff line number
Diff line change
@@ -22,7 +22,7 @@ Authentication
22
22
23
23
Most APIs will not run unless provided a valid authentication token. When running contract tests, Specmatic needs to obtain a valid auth token to call authenticated APIs.
24
24
25
-
You can see how this in action in the [sample petstore project](https://github.com/znsio/petstore).
25
+
You can see how this in action in the [sample petstore project](https://github.com/specmatic/petstore).
26
26
27
27
Here's a quick walk through of how it works.
28
28
@@ -32,11 +32,11 @@ First off, write the contract of the auth API, and in it, declare tokens such as
32
32
33
33
In step 3, Specmatic will run this as as a test against the auth service to get the auth tokens. So we must provide the base url of the actual auth service in environment configuration.
34
34
35
-
Here's a [the petstore's auth contract](https://github.com/znsio/petstore-contracts/blob/master/in/specmatic/examples/petstore/auth.spec).
35
+
Here's a [the petstore's auth contract](https://github.com/specmatic/petstore-contracts/blob/master/in/specmatic/examples/petstore/auth.spec).
36
36
37
37
### Setup the auth credentials
38
38
39
-
Look at the Examples table, in which we use the variables `$username` and `$password`. We do not hardcode them, because each environment (local, staging, etc) will need different auth credentials. These values come from environment configuration, where we can specify the auth credentials needed by each environment. See how this is done in `specmatic.json` in the [sample petstore application](https://github.com/znsio/petstore/blob/master/specmatic.json).
39
+
Look at the Examples table, in which we use the variables `$username` and `$password`. We do not hardcode them, because each environment (local, staging, etc) will need different auth credentials. These values come from environment configuration, where we can specify the auth credentials needed by each environment. See how this is done in `specmatic.json` in the [sample petstore application](https://github.com/specmatic/petstore/blob/master/specmatic.json).
40
40
41
41
Note how we have declared two variables, username and password, in the staging environment:
42
42
@@ -88,7 +88,7 @@ And export cookie = response-header.Cookie
88
88
89
89
Next we must connect auth contract with the actual contract that needs it.
90
90
91
-
Have a look at the sample petstore contract [api_petstore_v1.spec](https://github.com/znsio/petstore-contracts/blob/master/in/specmatic/examples/petstore/api_petstore_v1.spec).
91
+
Have a look at the sample petstore contract [api_petstore_v1.spec](https://github.com/specmatic/petstore-contracts/blob/master/in/specmatic/examples/petstore/api_petstore_v1.spec).
92
92
93
93
You'll see in the background:
94
94
@@ -121,14 +121,14 @@ In `($auth.token)`, `auth` is the `value` that we declared above, and `token` is
121
121
## 3. Run the contract tests
122
122
123
123
### Declare the application contract in specmatic.json
124
-
Make sure to declare the contract you're running as a test in [the Specmatic configuration](documentation/../configuration.html). Take a look at [specmatic.json in the petstore sample project](https://github.com/znsio/petstore/blob/master/specmatic.json) for an example of this. You can read more about [running contract tests using Specmatic here](documentation/../contract_tests.html).
124
+
Make sure to declare the contract you're running as a test in [the Specmatic configuration](documentation/../configuration.html). Take a look at [specmatic.json in the petstore sample project](https://github.com/specmatic/petstore/blob/master/specmatic.json) for an example of this. You can read more about [running contract tests using Specmatic here](documentation/../contract_tests.html).
125
125
126
126
### Execute the tests
127
127
Finally, run the tests. You must specify the environment while doing so, for Specmatic to pick up the variables and baseurls relevant to that environment.
128
128
129
129
If you're running the tests from a terminal, the command is `specmatic test --env=staging specfile.spec`
130
130
131
-
If you're running the tests from code, set a property named `environments`. Take a look at the [petstore sample](https://github.com/znsio/petstore/blob/master/src/test/java/com/petstore/test/PetStoreContractTest.java) to see an example of this.
131
+
If you're running the tests from code, set a property named `environments`. Take a look at the [petstore sample](https://github.com/specmatic/petstore/blob/master/src/test/java/com/petstore/test/PetStoreContractTest.java) to see an example of this.
Copy file name to clipboardExpand all lines: documentation/authentication.md
+7-7Lines changed: 7 additions & 7 deletions
Original file line number
Diff line number
Diff line change
@@ -116,27 +116,27 @@ So for Contract as Test we recommend having a “Test Security Configuration”
116
116
117
117
### OAuth2
118
118
119
-
Please refer to this [sample API](https://github.com/znsio/specmatic-order-contracts/blob/main/io/specmatic/examples/store/openapi/api_order_with_oauth_v3.yaml) specification which leverages [OAuth2](https://spec.openapis.org/oas/v3.0.1#implicit-oauth2-sample) to protect all endpoints that add, modify or delete data.
119
+
Please refer to this [sample API](https://github.com/specmatic/specmatic-order-contracts/blob/main/io/specmatic/examples/store/openapi/api_order_with_oauth_v3.yaml) specification which leverages [OAuth2](https://spec.openapis.org/oas/v3.0.1#implicit-oauth2-sample) to protect all endpoints that add, modify or delete data.
120
120
121
121
#### Wiring up dummy / mock authentication
122
122
123
123
124
124
125
-
Please refer to [sample springboot application](https://github.com/znsio/specmatic-order-api-java-with-oauth) that implements the [API](https://github.com/znsio/specmatic-order-contracts/blob/main/io/specmatic/examples/store/openapi/api_order_with_oauth_v3.yaml) we saw above.
125
+
Please refer to [sample springboot application](https://github.com/specmatic/specmatic-order-api-java-with-oauth) that implements the [API](https://github.com/specmatic/specmatic-order-contracts/blob/main/io/specmatic/examples/store/openapi/api_order_with_oauth_v3.yaml) we saw above.
126
126
127
127
### API Key Authentication
128
128
129
-
Please refer to this [sample API](https://github.com/znsio/specmatic-order-contracts/blob/main/io/specmatic/examples/store/openapi/api_order_v3.yaml) specification which leverages [ApiKeyAuth](https://spec.openapis.org/oas/v3.0.1#api-key-sample) to protect all endpoints that add, modify or delete data.
129
+
Please refer to this [sample API](https://github.com/specmatic/specmatic-order-contracts/blob/main/io/specmatic/examples/store/openapi/api_order_v3.yaml) specification which leverages [ApiKeyAuth](https://spec.openapis.org/oas/v3.0.1#api-key-sample) to protect all endpoints that add, modify or delete data.
130
130
131
131
#### Wiring up dummy / mock authentication
132
132
133
-
Please refer to [sample springboot application](https://github.com/znsio/specmatic-order-api-java) that implements the [API](https://github.com/znsio/specmatic-order-contracts/blob/main/io/specmatic/examples/store/openapi/api_order_v3.yaml) we saw above.
133
+
Please refer to [sample springboot application](https://github.com/specmatic/specmatic-order-api-java) that implements the [API](https://github.com/specmatic/specmatic-order-contracts/blob/main/io/specmatic/examples/store/openapi/api_order_v3.yaml) we saw above.
134
134
135
135
This has two API security configurations
136
-
* [Production Security Config](https://github.com/znsio/specmatic-order-api-java/blob/main/src/main/java/com/store/config/SecurityConfig.kt) - This fetches user from the DB based on api token in request header
137
-
* [Test Security Config](https://github.com/znsio/specmatic-order-api-java/blob/main/src/test/java/com/store/config/TestSecurityConfig.kt) - This always returns a dummy user principal. However rest of the code such as reading the authentication token from header etc. are still tested.
136
+
* [Production Security Config](https://github.com/specmatic/specmatic-order-api-java/blob/main/src/main/java/com/store/config/SecurityConfig.kt) - This fetches user from the DB based on api token in request header
137
+
* [Test Security Config](https://github.com/specmatic/specmatic-order-api-java/blob/main/src/test/java/com/store/config/TestSecurityConfig.kt) - This always returns a dummy user principal. However rest of the code such as reading the authentication token from header etc. are still tested.
138
138
139
-
So when you run the [ContractTest](https://github.com/znsio/specmatic-order-api-java/blob/main/src/test/java/com/store/ContractTest.java) it will still exercise your security plumbing (does the application accept the proper header name, datatype, etc.).
139
+
So when you run the [ContractTest](https://github.com/specmatic/specmatic-order-api-java/blob/main/src/test/java/com/store/ContractTest.java) it will still exercise your security plumbing (does the application accept the proper header name, datatype, etc.).
140
140
141
141
This is just an example of how we can wire up security configurations for test and production environments. Even in SpringBoot you can leverage other techniques such as [Spring Profiles](https://docs.spring.io/spring-boot/docs/1.2.0.M1/reference/html/boot-features-profiles.html) to achieve the same effect.
0 commit comments