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
The project has limited support for describing security requirements of an API.
340
+
The project has limited support for describing security requirements of an API.
341
341
Currently we only support Oauth2 with [JWT](https://jwt.io/) tokens and HTTP Basic Auth.
342
342
343
-
`restdocs-api-spec` inspects the `AUTHORIZATION` header of a request for a `JWT` token.
343
+
`restdocs-api-spec` inspects the `AUTHORIZATION` header of a request for a `JWT` token.
344
344
Also the a HTTP basic authorization header is discovered and documented.
345
-
If such a token is found the scopes are extracted and added to the `resource.json` snippet.
345
+
If such a token is found the scopes are extracted and added to the `resource.json` snippet.
346
346
347
-
The `restdocs-api-spec-gradle-plugin` will consider this information if the `oauth2SecuritySchemeDefinition` configuration option is set (see [Gradle plugin configuration](#gradle-plugin-configuration)).
348
-
This will result in a top-level `securityDefinitions` in the OpenAPI definition.
347
+
The `restdocs-api-spec-gradle-plugin` will consider this information if the `oauth2SecuritySchemeDefinition` configuration option is set (see [Gradle plugin configuration](#gradle-plugin-configuration)).
348
+
This will result in a top-level `securityDefinitions` in the OpenAPI definition.
349
349
Additionally the required scopes will be added in the `security` section of an `operation`.
350
350
351
351
### Running the gradle plugin
@@ -388,7 +388,7 @@ separatePublicApi | Should the plugin generate additional API specification file
388
388
outputDirectory |The output directory for the API specification files | `build/api-spec`
389
389
snippetsDirectory |The directory SpringRESTDocs generated the snippets to | `build/generated-snippets`
390
390
391
-
#### CommonOpenAPI configuration
391
+
#### CommonOpenAPI configuration
392
392
393
393
The `restdocs-api-spec-gradle-plugin` takes the following configuration options forOpenAPI2.0 and OpenAPI3.0.1- all are optional.
394
394
@@ -487,14 +487,14 @@ servers = [ {
487
487
} ]
488
488
```
489
489
490
-
The same structure applies to `server`.
490
+
The same structure applies to `server`.
491
491
A single server can also be specified using a plain string:
492
492
493
493
```
494
494
server ='http://some.api/api'
495
495
```
496
496
497
-
#### Postman
497
+
#### Postman
498
498
499
499
The `restdocs-api-spec-gradle-plugin` takes the following configuration options forPostman collections - all are optional.
This project supersedes [restdocs-raml](https://github.com/ePages-de/restdocs-raml).
531
-
Soif you are coming from `restdocs-raml` you might want to switch to `restdocs-api-spec`.
530
+
This project supersedes [restdocs-raml](https://github.com/ePages-de/restdocs-raml).
531
+
Soif you are coming from `restdocs-raml` you might want to switch to `restdocs-api-spec`.
532
532
533
533
TheAPI of both projects is fairly similar and it is easy to migrate.
534
534
535
-
We plan to support RAML in the future.
535
+
We plan to support RAML in the future.
536
536
In the meantime you can use one of several ways to convert an OpenAPI specification to RAML.
537
537
There are converters around that can help you to achieve this conversion.
538
538
539
539
- [oas-raml-converter](https://github.com/mulesoft/oas-raml-converter) - an npm project that provides a CLI to convert between OpenAPI and RAML - it also provides an [online converter](https://mulesoft.github.io/oas-raml-converter/)
540
540
- [api-matic](https://apimatic.io/transformer) - an online converter capable of converting between many api specifications
541
541
542
-
In the [sample project](samples/restdocs-api-spec-sample) you find a build configuration that uses the [oas-raml-converter-docker](https://hub.docker.com/r/zaddo/oas-raml-converter-docker/) docker image and the [gradle-docker-plugin](https://github.com/bmuschko/gradle-docker-plugin) to leverage the `oas-raml-converter` to convert the output of the `openapi` task to RAML.
542
+
In the [sample project](samples/restdocs-api-spec-sample) you find a build configuration that uses the [oas-raml-converter-docker](https://hub.docker.com/r/zaddo/oas-raml-converter-docker/) docker image and the [gradle-docker-plugin](https://github.com/bmuschko/gradle-docker-plugin) to leverage the `oas-raml-converter` to convert the output of the `openapi` task to RAML.
543
543
Usingthis approach your gradle build can still output a RAML specification.
544
544
545
545
See [openapi2raml.gradle](samples/restdocs-api-spec-sample/openapi2raml.gradle).
0 commit comments