{"id":13678241,"url":"https://github.com/ePages-de/restdocs-api-spec","last_synced_at":"2025-04-29T12:34:20.726Z","repository":{"id":41192376,"uuid":"139841727","full_name":"ePages-de/restdocs-api-spec","owner":"ePages-de","description":"Adds API specification support to Spring REST Docs","archived":false,"fork":false,"pushed_at":"2024-05-06T14:35:57.000Z","size":991,"stargazers_count":364,"open_issues_count":48,"forks_count":98,"subscribers_count":19,"default_branch":"master","last_synced_at":"2024-05-07T11:29:28.558Z","etag":null,"topics":["openapi","openapi-documentation","rest-api-documentation","spring","spring-rest-docs"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ePages-de.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2018-07-05T11:47:48.000Z","updated_at":"2024-08-02T13:16:54.456Z","dependencies_parsed_at":"2024-02-21T15:32:58.670Z","dependency_job_id":"6cb5fe4c-f985-4e6a-8bbf-7d482ab95e11","html_url":"https://github.com/ePages-de/restdocs-api-spec","commit_stats":null,"previous_names":[],"tags_count":76,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ePages-de%2Frestdocs-api-spec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ePages-de%2Frestdocs-api-spec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ePages-de%2Frestdocs-api-spec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ePages-de%2Frestdocs-api-spec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ePages-de","download_url":"https://codeload.github.com/ePages-de/restdocs-api-spec/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224173678,"owners_count":17268153,"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":["openapi","openapi-documentation","rest-api-documentation","spring","spring-rest-docs"],"created_at":"2024-08-02T13:00:51.431Z","updated_at":"2024-11-11T20:31:14.360Z","avatar_url":"https://github.com/ePages-de.png","language":"Kotlin","readme":"# Spring REST Docs API specification Integration\n\n[![oss lifecycle](https://img.shields.io/badge/oss_lifecycle-maintenance-yellow.svg)](https://github.com/ePages-de/restdocs-api-spec/issues/204)\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=ePages-de_restdocs-api-spec\u0026metric=coverage)](https://sonarcloud.io/summary/new_code?id=ePages-de_restdocs-api-spec)\n![](https://img.shields.io/github/license/ePages-de/restdocs-openapi.svg)\n[![Maven Central](https://img.shields.io/maven-central/v/com.epages/restdocs-api-spec)](https://search.maven.org/artifact/com.epages/restdocs-api-spec)\n[![Gitter](https://img.shields.io/gitter/room/nwjs/nw.js.svg)](https://gitter.im/restdocs-api-spec/Lobby)\n\nThis is an extension that adds API specifications as an output format to [Spring REST Docs](https://projects.spring.io/spring-restdocs/).\nIt currently supports:\n- [OpenAPI 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) in `json` and `yaml`\n- [OpenAPI 3.0.1](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md) in `json` and `yaml`\n- [Postman Collections 2.1.0](https://schema.getpostman.com/json/collection/v2.1.0/docs/index.html)\n\nPlease note that this extension was developed for JSON-based APIs.\nWe do not expect this extension to build usable API specification for non-JSON request or response bodies.\n\n## Motivation\n\n[Spring REST Docs](https://projects.spring.io/spring-restdocs/) is a great tool to produce documentation for your RESTful services that is accurate and readable.\n\nWe especially like its test-driven approach and this is the main reason why we chose it.\n\nIt offers support for AsciiDoc and Markdown. This is great for generating simple HTML-based documentation.\nBut both are markup languages and thus it is hard to get any further than statically generated HTML.\n\nAPI specifications like OpenAPI are a lot more flexible.\nWith e.g. OpenAPI you get a machine-readable description of your API. There is a rich ecosystem around it that contains tools to:\n- generate a HTML representation of your API - [ReDoc](https://github.com/Rebilly/ReDoc)\n- generate an interactive API reference - e.g. using services like [stoplight.io](https://stoplight.io) or [readme.io](https://readme.io)\n\nAlso, API specifications like OpenAPI are supported by many REST clients like [Postman](https://www.getpostman.com) and [Paw](https://paw.cloud).\nThus having an API specification for a REST API is a great plus when starting to work with it.\n\nThe most common use case to generate an OpenAPI specification is code introspection and adding documentation related annotations to your code.\nWe do not like enriching our production code with this information and clutter it with even more annotations.\nWe agree with Spring REST Docs that the test-driven way to produce accurate API documentation is the way to go.\nThis is why we came up with this project.\n\n\n- [Motivation](#motivation)\n- [Getting started](#getting-started)\n    - [Version compatibility](#version-compatibility)\n    - [Project structure](#project-structure)\n    - [Build configuration](#build-configuration)\n        - [Gradle](#gradle)\n        - [Maven](#maven)\n    - [Usage with Spring REST Docs](#usage-with-spring-rest-docs)\n    - [Documenting Bean Validation constraints](#documenting-bean-validation-constraints)\n    - [Migrate existing Spring REST Docs tests](#migrate-existing-spring-rest-docs-tests)\n        - [MockMvc based tests](#mockmvc-based-tests)\n        - [REST Assured based tests](#rest-assured-based-tests)\n        - [WebTestClient based tests](#webtestclient-based-tests)\n    - [Security Definitions in OpenAPI](#security-definitions-in-openapi)\n    - [Running the gradle plugin](#running-the-gradle-plugin)\n        - [OpenAPI 2.0](#openapi-20)\n        - [OpenAPI 3.0.1](#openapi-301)\n        - [Postman](#postman)\n    - [Gradle plugin configuration](#gradle-plugin-configuration)\n        - [Common configuration for all formats](#common-configuration-for-all-formats)\n        - [Common OpenAPI configuration](#common-openapi-configuration)\n        - [OpenAPI 2.0](#openapi-20-1)\n        - [OpenAPI 3.0.1](#openapi-301-1)\n        - [Postman](#postman-1)\n- [Generate an HTML-based API reference from OpenAPI](#generate-an-html-based-api-reference-from-openapi)\n\n## Getting started\n\n### Version compatibility\n\nSpring Boot and Spring REST Docs 3.0.0 introduced [breaking chances to how request parameters are documented: `RequestParameterSnippet` was split into `QueryParameterSnippet` and `FormParameterSnippet`.](https://github.com/spring-projects/spring-restdocs/issues/832)\n\n|Spring Boot version | restdocs-api-spec version|\n|---|---|\n|3.x|0.17.1 or later|\n|2.x|0.16.4|\n\n### Project structure\n\nThe project consists of the following main components:\n\n- [restdocs-api-spec](restdocs-api-spec) - contains the actual Spring REST Docs extension.\nThis is most importantly the [ResourceDocumentation](restdocs-api-spec/src/main/kotlin/com/epages/restdocs/apispec/ResourceDocumentation.kt) which is the entry point to use the extension in your tests.\nThe [ResourceSnippet](restdocs-api-spec/src/main/kotlin/com/epages/restdocs/apispec/ResourceSnippet.kt) is the snippet used to produce a json file `resource.json` containing all the details about the documented resource.\n- [restdocs-api-spec-mockmvc](restdocs-api-spec-mockmvc) - contains a wrapper for `MockMvcRestDocumentation` for easier migration to `restdocs-api-spec` from MockMvc tests that use plain `spring-rest-docs-mockmvc`.\n- [restdocs-api-spec-restassured](restdocs-api-spec-restassured) - contains a wrapper for `RestAssuredRestDocumentation` for easier migration to `restdocs-api-spec` from [Rest Assured](http://rest-assured.io) tests that use plain `spring-rest-docs-restassured`.\n- [restdocs-api-spec-gradle-plugin](restdocs-api-spec-gradle-plugin) - adds a gradle plugin that aggregates the `resource.json` files produced  by `ResourceSnippet` into an API specification file for the whole project.\n\n### Build configuration\n\n#### Gradle\n\n1. Add the plugin\n    * Using the [plugins DSL](https://docs.gradle.org/current/userguide/plugins.html#sec:plugins_block):\n        ```groovy\n        plugins {\n            id 'com.epages.restdocs-api-spec' version '0.18.2'\n        }\n        ```\n        Examples with Kotlin are also available [here](https://plugins.gradle.org/plugin/com.epages.restdocs-api-spec)\n    * __OR__ Using [legacy plugin application](https://docs.gradle.org/current/userguide/plugins.html#sec:old_plugin_application):\n        * *1.1* Use of `buildscript` requires you to add the `https://plugins.gradle.org/m2/` repository.\n        * *1.2* add the dependency to `restdocs-api-spec-gradle-plugin`\n        * *1.3* apply `restdocs-api-spec-gradle-plugin`\n        ```groovy\n        buildscript {\n          repositories {\n            maven {\n              url \"https://plugins.gradle.org/m2/\" //1.1\n            }\n          }\n          dependencies {\n            classpath \"com.epages:restdocs-api-spec-gradle-plugin:0.18.2\" //1.2\n          }\n        }\n\n        apply plugin: 'com.epages.restdocs-api-spec' //1.3\n\n        ```\n2. Add required dependencies to your tests\n    * *2.1* add the `mavenCentral` repository used to resolve the `com.epages:restdocs-api-spec` module of the project.\n    * *2.2* add the actual `restdocs-api-spec-mockmvc` dependency to the test scope. Use `restdocs-api-spec-restassured` if you use `RestAssured` instead of `MockMvc`.\n    * *2.3* add configuration options for `restdocs-api-spec-gradle-plugin`. See [Gradle plugin configuration](#gradle-plugin-configuration)\n    ```groovy\n\n    repositories { //2.1\n        mavenCentral()\n    }\n\n    dependencies {\n        //..\n        testImplementation('com.epages:restdocs-api-spec-mockmvc:0.18.2') //2.2\n    }\n\n    openapi { //2.3\n        host = 'localhost:8080'\n        basePath = '/api'\n        title = 'My API'\n        description = 'My API description'\n        tagDescriptionsPropertiesFile = 'src/docs/tag-descriptions.yaml'\n        version = '1.0.0'\n        format = 'json'\n    }\n\n    openapi3 {\n        server = 'https://localhost:8080'\n        title = 'My API'\n        description = 'My API description'\n        tagDescriptionsPropertiesFile = 'src/docs/tag-descriptions.yaml'\n        version = '0.1.0'\n        format = 'yaml'\n    }\n\n    postman {\n        title = 'My API'\n        version = '0.1.0'\n        baseUrl = 'https://localhost:8080'\n    }\n    ```\n\nSee the [build.gradle](samples/restdocs-api-spec-sample/build.gradle) for the setup used in the sample project.\n\n#### Maven\n\nThe root project does not provide a maven plugin.\nBut you can find a plugin that works with `restdocs-api-spec` at [BerkleyTechnologyServices/restdocs-spec](https://github.com/BerkleyTechnologyServices/restdocs-spec).\n\n### Usage with Spring REST Docs\n\nThe class [ResourceDocumentation](restdocs-api-spec/src/main/kotlin/com/epages/restdocs/apispec/ResourceDocumentation.kt) contains the entry point for using the [ResourceSnippet](restdocs-api-spec/src/main/kotlin/com/epages/restdocs/apispec/ResourceSnippet.kt).\n\nThe most basic form does not take any parameters:\n\n```java\nmockMvc\n  .perform(post(\"/carts\"))\n  .andDo(document(\"carts-create\", resource(\"Create a cart\")));\n```\n\nThis test will produce the `resource.json` file in the snippets directory.\nThis file just contains all the information that we can collect about the resource.\nThe format of this file is not specific to an API specification.\n\n```json\n{\n  \"operationId\" : \"carts-create\",\n  \"summary\" : \"Create a cart\",\n  \"description\" : \"Create a cart\",\n  \"privateResource\" : false,\n  \"deprecated\" : false,\n  \"request\" : {\n    \"path\" : \"/carts\",\n    \"method\" : \"POST\",\n    \"contentType\" : null,\n    \"headers\" : [ ],\n    \"pathParameters\" : [ ],\n    \"requestParameters\" : [ ],\n    \"requestFields\" : [ ],\n    \"example\" : null,\n    \"securityRequirements\" : null\n  },\n  \"response\" : {\n    \"status\" : 201,\n    \"contentType\" : \"application/hal+json\",\n    \"headers\" : [ ],\n    \"responseFields\" : [ ],\n    \"example\" : \"{\\n  \\\"total\\\" : 0,\\n  \\\"products\\\" : [ ],\\n  \\\"_links\\\" : {\\n    \\\"self\\\" : {\\n      \\\"href\\\" : \\\"http://localhost:8080/carts/4\\\"\\n    },\\n    \\\"order\\\" : {\\n      \\\"href\\\" : \\\"http://localhost:8080/carts/4/order\\\"\\n    }\\n  }\\n}\"\n  }\n}\n```\n\nJust like with Spring REST Docs we can also describe request fields, response fields, path variables, parameters, headers, and links.\nFurthermore you can add a text description and a summary for your resource.\nThe extension also discovers `JWT` tokens in the `Authorization` header and will document the required scopes from it. Also basic auth headers are discovered and documented.\n\nThe following example uses `ResourceSnippetParameters` to document response fields, path parameters, and links.\nWe paid close attention to keep the API as similar as possible to what you already know from Spring REST Docs.\n`fieldWithPath` and `linkWithRel` are actually still the static methods you would use in your using Spring REST Docs test.\n\n```java\nmockMvc.perform(get(\"/carts/{id}\", cartId)\n  .accept(HAL_JSON))\n  .andExpect(status().isOk())\n  .andDo(document(\"cart-get\",\n    resource(ResourceSnippetParameters.builder()\n      .description(\"Get a cart by id\")\n      .pathParameters(\n        parameterWithName(\"id\").description(\"the cart id\"))\n      .responseFields(\n        fieldWithPath(\"total\").description(\"Total amount of the cart.\"),\n        fieldWithPath(\"products\").description(\"The product line item of the cart.\"),\n        subsectionWithPath(\"products[]._links.product\").description(\"Link to the product.\"),\n        fieldWithPath(\"products[].quantity\").description(\"The quantity of the line item.\"),\n        subsectionWithPath(\"products[].product\").description(\"The product the line item relates to.\"),\n        subsectionWithPath(\"_links\").description(\"Links section.\"))\n      .links(\n        linkWithRel(\"self\").ignored(),\n        linkWithRel(\"order\").description(\"Link to order the cart.\"))\n    .build())));\n```\nPlease see the [CartIntegrationTest](samples/restdocs-api-spec-sample/src/test/java/com/epages/restdocs/apispec/sample/CartIntegrationTest.java) in the sample application for a detailed example.\n\n**:warning: Use `template URIs` to refer to path variables in your request**\n\nNote how we use the `urlTemplate` to build the request with [`RestDocumentationRequestBuilders`](https://docs.spring.io/spring-restdocs/docs/current/api/org/springframework/restdocs/mockmvc/RestDocumentationRequestBuilders.html#get-java.lang.String-java.lang.Object...-).\nThis makes the `urlTemplate` available in the snippet and we can depend on the non-expanded template when generating the OpenAPI file.\n\n ```java\nmockMvc.perform(get(\"/carts/{id}\", cartId)\n ```\n\n### Documenting Bean Validation constraints\n\nSimilar to the way Spring REST Docs allows to use [bean validation constraints](https://docs.spring.io/spring-restdocs/docs/current/reference/html5/#documenting-your-api-constraints) to enhance your documentation, you can also use the constraints from your model classes to let `restdocs-api-spec` enrich the generated JsonSchemas.\n`restdocs-api-spec` provides the class [com.epages.restdocs.apispec.ConstrainedFields](restdocs-api-spec/src/main/kotlin/com/epages/restdocs/apispec/ConstrainedFields.kt) to generate `FieldDescriptor`s that contain information about the constraints on this field.\n\nCurrently the following constraints are considered when generating JsonSchema from `FieldDescriptor`s that have been created via `com.epages.restdocs.apispec.ConstrainedFields`\n- `NotNull`, `NotEmpty`, and `NotBlank` annotated fields become required fields in the JsonSchema\n- for String fields annotated with `NotEmpty`, and `NotBlank` the `minLength` constraint in JsonSchema is set to 1\n- for String fields annotated with `Length` the `minLength` and `maxLength` constraints in JsonSchema are set to the value of the corresponding attribute of the annotation\n- for String fields annotated with `Pattern`, the pattern constraint is propagated to JsonSchema\n- for Number fields annotated with `Min`, the `minimum` constraint is propagated to JsonSchema\n- for Number fields annotated with `Max`, the `maximum` constraint is propagated to JsonSchema\n- for Number fields annotated with `Size` the `minimum` and `maximum` constraints in JsonSchema are set to the value of the corresponding attribute of the annotation\n\nIf you already have your own `ConstraintFields` implementation you can also add the logic from `com.epages.restdocs.apispec.ConstrainedFields` to your own class.\nHere it is important to add the constraints under the key `validationConstraints` into the attributes map if the `FieldDescriptor`.\n\n### Migrate existing Spring REST Docs tests\n\n#### MockMvc based tests\n\nFor convenience when applying `restdocs-api-spec` to an existing project that uses Spring REST Docs, we introduced [com.epages.restdocs.apispec.MockMvcRestDocumentationWrapper](restdocs-api-spec-mockmvc/src/main/kotlin/com/epages/restdocs/apispec/MockMvcRestDocumentationWrapper.kt).\n\nIn your tests you can just replace calls to `MockMvcRestDocumentation.document` with the corresponding variant of `MockMvcRestDocumentationWrapper.document`.\n\n`MockMvcRestDocumentationWrapper.document` will execute the specified snippets and also add a `ResourceSnippet` equipped with the input from your snippets.\n\nHere is an example:\n\n```java\nresultActions\n  .andDo(\n    MockMvcRestDocumentationWrapper.document(operationName,\n      requestFields(new FieldDescriptors().getFieldDescriptors()),\n      responseFields(\n        fieldWithPath(\"comment\").description(\"the comment\"),\n        fieldWithPath(\"flag\").description(\"the flag\"),\n        fieldWithPath(\"count\").description(\"the count\"),\n        fieldWithPath(\"id\").description(\"id\"),\n        fieldWithPath(\"_links\").ignored()\n      ),\n      links(linkWithRel(\"self\").description(\"some\"))\n  )\n);\n```\n\nThis will do exactly what `MockMvcRestDocumentation.document` does.\nAdditionally it will add a `ResourceSnippet` with the descriptors you provided in the `RequestFieldsSnippet`, `ResponseFieldsSnippet`, and `LinksSnippet`.\n\n#### REST Assured based tests\n\nAlso for REST Assured we offer a convenience wrapper similar to `MockMvcRestDocumentationWrapper`.\nThe usage for REST Assured is also similar to MockMVC, except that [com.epages.restdocs.apispec.RestAssuredRestDocumentationWrapper](restdocs-api-spec/src/main/kotlin/com/epages/restdocs/apispec/RestAssuredRestDocumentationWrapper.kt) is used instead of [com.epages.restdocs.apispec.MockMvcRestDocumentationWrapper](restdocs-api-spec/src/main/kotlin/com/epages/restdocs/apispec/MockMvcRestDocumentationWrapper.kt).\n\nTo use the `RestAssuredRestDocumentationWrapper`, you have to add a dependency to [restdocs-api-spec-restassured](restdocs-api-spec-restassured) to your build.\n```java\nRestAssured.given(this.spec)\n        .filter(RestAssuredRestDocumentationWrapper.document(\"{method-name}\",\n                \"The API description\",\n                requestParameters(\n                        parameterWithName(\"param\").description(\"the param\")\n                ),\n                responseFields(\n                        fieldWithPath(\"doc.timestamp\").description(\"Creation timestamp\")\n                )\n        ))\n        .when()\n        .queryParam(\"param\", \"foo\")\n        .get(\"/restAssuredExample\")\n        .then()\n        .statusCode(200);\n```\n\n#### WebTestClient based tests\n\nWe also offer a convenience wrapper for `WebTestClient` which works similar to `MockMvcRestDocumentationWrapper`.\nThe usage is similar to MockMVC, except that [com.epages.restdocs.apispec.WebTestClientRestDocumentationWrapper](restdocs-api-spec-webtestclient/src/main/kotlin/com/epages/restdocs/apispec/WebTestClientRestDocumentationWrapper.kt) is used instead of [com.epages.restdocs.apispec.MockMvcRestDocumentationWrapper](restdocs-api-spec/src/main/kotlin/com/epages/restdocs/apispec/MockMvcRestDocumentationWrapper.kt).\n\nTo use the `WebTestClientRestDocumentationWrapper`, you will have to add a dependency to [restdocs-api-spec-webtestclient](restdocs-api-spec-webtestclient) to your build.\n\n```\nwebTestClient.get().uri(\"/sample/{id}?queryParam=something\", \"1024\").exchange()\n    .expectStatus().isOk().expectBody()\n    .consumeWith(\n        WebTestClientRestDocumentationWrapper\n            .document(\"sample\",\n                RequestDocumentation.pathParameters(\n                    parameterWithName(\"id\").description(\n                        \"description of the path parameter\")\n                ),\n                RequestDocumentation.requestParameters(\n                    parameterWithName(\"queryParam\").description(\n                        \"description of the query parameter\")\n                ),\n                HeaderDocumentation.responseHeaders(\n                    headerWithName(HttpHeaders.CONTENT_TYPE)\n                        .description(MediaType.APPLICATION_JSON_UTF8_VALUE)\n                ),\n                responseFields(\n                    PayloadDocumentation.fieldWithPath(\"field1\").type(JsonFieldType.STRING)\n                        .description(\"description of field1\"),\n                    PayloadDocumentation.fieldWithPath(\"field2\").type(JsonFieldType.STRING)\n                        .description(\"description of field2\")\n                )\n            )\n    );\n```\n\n### Security Definitions in OpenAPI\n\nThe project has limited support for describing security requirements of an API.\nCurrently we only support Oauth2 with [JWT](https://jwt.io/) tokens and HTTP Basic Auth.\n\n`restdocs-api-spec` inspects the `AUTHORIZATION` header of a request for a `JWT` token.\nAlso the a HTTP basic authorization header is discovered and documented.\nIf such a token is found the scopes are extracted and added to the `resource.json` snippet.\n\nThe `restdocs-api-spec-gradle-plugin` will consider this information if the `oauth2SecuritySchemeDefinition` configuration option is set (see [Gradle plugin configuration](#gradle-plugin-configuration)).\nThis will result in a top-level `securityDefinitions` in the OpenAPI definition.\nAdditionally the required scopes will be added in the `security` section of an `operation`.\n\n### Running the gradle plugin\n\n`restdocs-api-spec-gradle-plugin` is responsible for picking up the generated `resource.json` files and aggregate them into an API specification.\n\n#### OpenAPI 2.0\nIn order to generate an OpenAPI 2.0 specification we use the `openapi` task:\n\n```\n./gradlew openapi\n```\n\n#### OpenAPI 3.0.1\nIn order to generate an OpenAPI 3.0.1 specification we use the `openapi3` task:\n\n```\n./gradlew openapi3\n```\n\nFor our [sample project](samples/restdocs-api-spec-sample) this creates a `openapi3.yaml` file in the output directory (`build/api-spec`).\n\n### Postman\n\nIn order to generate a [Postman collection](https://www.getpostman.com/collection) we use the `postman` task:\n\n```\n./gradlew postman\n```\n\nFor our [sample project](samples/restdocs-api-spec-sample) this creates a `postman-collection.json` file in the output directory (`build/api-spec`).\n\n### Gradle plugin configuration\n\n#### Common configuration for all formats\n\nName | Description | Default value\n---- | ----------- | -------------\nseparatePublicApi | Should the plugin generate additional API specification files which do **not** contain the resources marked as private | `false`\noutputDirectory | The output directory for the API specification files | `build/api-spec`\nsnippetsDirectory | The directory Spring REST Docs generated the snippets to | `build/generated-snippets`\n\n#### Common OpenAPI configuration\n\nThe `restdocs-api-spec-gradle-plugin` takes the following configuration options for OpenAPI 2.0 and OpenAPI 3.0.1 - all are optional.\n\nName | Description | Default value\n---- | ----------- | -------------\ntitle | The title of the application. Used for the `title` attribute in the [Info object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#info-object) | `API documentation`\ndescription | A description of the application. Used for the `description` attribute in the [Info object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#info-object) | empty\nversion | The version of the api. Used for the `version` attribute in the [Info object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#info-object) | project version\nformat | The format of the output OpenAPI file - supported values are `json` and `yaml` | `json`\ntagDescriptionsPropertiesFile | A yaml file mapping tag names to descriptions. These are populated into the top level ` [Tags attribute](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#tag-object) | no default - if not provided no tags created.\noauth2SecuritySchemeDefinition | Closure containing information to generate the [securityDefinitions](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#securityDefinitionsObject) object in the `OpenAPI` specification. | empty\noauth2SecuritySchemeDefinition.flows | The Oauth2 flows the API supports. Use valid values from the [securityDefinitions](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#securityDefinitionsObject) specification. | no default - required if `oauth2SecuritySchemeDefinition` is set.\noauth2SecuritySchemeDefinition.tokenUrl | The Oauth2 tokenUrl | no default - required for the flows `password`, `application`, `accessCode`.\noauth2SecuritySchemeDefinition.authorizationUrl | The Oauth2 authorizationUrl | no default - required for the flows `implicit`, `accessCode`.\noauth2SecuritySchemeDefinition.scopeDescriptionsPropertiesFile | A yaml file mapping scope names to descriptions. These are used in the `securityDefinitions` as the [scope description](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#scopesObject) | no default - if not provided the scope descriptions default to `No description`.\n\n\nThe `scopeDescriptionsPropertiesFile` is supposed to be a yaml file:\n```yaml\nscope-name: A description\n```\n#### OpenAPI 2.0\n\nThe `restdocs-api-spec-gradle-plugin` takes the following configuration options for OpenAPI 2.0 - all are optional.\n\nName | Description | Default value\n---- | ----------- | -------------\nhost | The host serving the API - corresponds to the attribute with the same name in the [OpenAPI root object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#swagger-object)| `localhost`\nbasePath | The base path on which the API is served - corresponds to the attribute with the same name in the [OpenAPI root object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#swagger-object) | null\nschemes | The supported transfer protocols of the API - corresponds to the attribute with the same name in the [OpenAPI root object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#swagger-object) | `['http'\"]`\noutputFileNamePrefix | The file name prefix of the output file. | `openapi` which results in e.g. `openapi.json` for the format `json`\n\nExample configuration closure:\n```\nopenapi {\n    basePath = \"/api\"\n    host = \"api-shop.beyondshop.cloud\"\n    schemes = [\"https\"]\n    format = \"yaml\"\n    title = 'Beyond REST API'\n    version = \"1.0.0\"\n    separatePublicApi = true\n    snippetsDirectory=\"src/docs/asciidoc/generated-snippets/\"\n    outputDirectory=\"openapi/\"\n    oauth2SecuritySchemeDefinition = {\n        flows = ['accessCode', 'application']\n        tokenUrl = 'https://api-shop.beyondshop.cloud/api/oauth/token'\n        authorizationUrl = 'https://api-shop.beyondshop.cloud/api/auth/oauth-ext/authorize'\n        scopeDescriptionsPropertiesFile = \"src/docs/scope-descriptions.yaml\"\n    }\n}\n```\n\n#### OpenAPI 3.0.1\n\nThe `restdocs-api-spec-gradle-plugin` takes the following configuration options for OpenAPI 3.0.1 - all are optional.\n\nName | Description | Default value\n---- | ----------- | -------------\noutputFileNamePrefix | The file name prefix of the output file. | `openapi3` which results in e.g. `openapi3.json` for the format `json`\nservers | Specifies the servers the API is available from. Use this property to specify multiple server definitions. See example below.  | `http://localhost`\nserver | Specifies the servers the API is available from. Use this property to specify just a single server definition. See example below | `http://localhost`\n\nExample configuration closure:\n```\nopenapi3 {\n    servers = [ { url = \"http://some.api\" } ]\n    title = 'My API title'\n    version = '1.0.1'\n    format = 'yaml'\n    contact = {\n        name = 'John Doe'\n        email = 'john.doe@example.com'\n    }\n    separatePublicApi = true\n    outputFileNamePrefix = 'my-api-spec'\n    oauth2SecuritySchemeDefinition = {\n        flows = ['authorizationCode']\n        tokenUrl = 'http://example.com/token'\n        authorizationUrl = 'http://example.com/authorize'\n        scopeDescriptionsPropertiesFile = \"scopeDescriptions.yaml\"\n    }\n}\n```\n\nExample `build.gradle.kts` configuration closure (by [axkb](https://github.com/axkb), [#112](https://github.com/ePages-de/restdocs-api-spec/issues/112)):\n```\nconfigure\u003ccom.epages.restdocs.apispec.gradle.OpenApi3Extension\u003e {\n    setServer(\"http://$apiHost:$apiPort\")\n    title = \"Your title\"\n    description = \"Your description\"\n    version = \"0.1.0\"\n    format = \"json\"\n    tagDescriptionsPropertiesFile = \"src/test/resources/tags.yaml\"\n}\n```\n\nThe `servers` and `server` property can also contain variables. Is this case the` property can be specified like this:\n\nThis configuration follows the same semantics as the ['Servers Object'](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#server-object) in the OpenAPI specification\n\n```\nservers = [ {\n    url = 'https://{host}/api'\n    variables = [\n        host: [\n            default: 'api-shop.beyondshop.cloud/api',\n            description: 'The hostname of your beyond shop',\n            enum: ['api-shop', 'oz']\n        ]\n    ]\n} ]\n```\n\nThe same structure applies to `server`.\nA single server can also be specified using a plain string:\n\n```\nserver = 'http://some.api/api'\n```\n\n#### Postman\n\nThe `restdocs-api-spec-gradle-plugin` takes the following configuration options for Postman collections - all are optional.\n\nName | Description | Default value\n---- | ----------- | -------------\ntitle | The title of the application. Used for the `name` attribute of the `Information` object of the collection | `API documentation`\nversion | The version of the api. Used for the `version` attribute in the `Information` object | project version if specified - otherwise `1.0.0`\nbaseUrl | The baseUrl of the application. e.g. `https://myapi.example.com:8080/api` | `http://localhost`\n\nExample configuration closure:\n```\npostman {\n    title = 'Beyond REST API'\n    version = '1.0.1'\n    baseUrl = 'https://api-shop.beyondshop.cloud/api'\n    separatePublicApi = true\n    outputFileNamePrefix = 'my-postman-collection'\n}\n```\n\n## Generate an HTML-based API reference from OpenAPI\n\nWe can use [redoc](https://github.com/Rebilly/ReDoc) to generate an HTML API reference from our OpenAPI specification.\n\nThe [redoc-cli](https://www.npmjs.com/package/redoc-cli) can be used to bundle (and serve) this API reference:\n```\n# Install redoc-cli\nnpm install -g redoc-cli\n\n# Bundle the documentation into a zero-dependency HTML-file\nredoc-cli bundle build/api-spec/openapi.json\n\n# Bundle and serve\nredoc-cli serve build/api-spec/openapi.json\n```\n\n## Maintenance\n\nThis section of the README is targeted at project maintainers.\n\n### Publish project\n\nThe project is published with the help of [GitHub Actions](./.github/workflows).\nIt's version number is determined by the Git tags (see [allegro/axion-release-plugin](https://axion-release-plugin.readthedocs.io)).\nThe Java dependencies are published to Sonatype with the help of the [gradle-nexus/publish-plugin](https://github.com/gradle-nexus/publish-plugin) and the Maven Publish Plugin.\nThe Gradle plugin is published to the [Gradle plugin portal](https://plugins.gradle.org/plugin/com.epages.restdocs-api-spec) with the help of the ['plugin-publish' plugin](https://plugins.gradle.org/plugin/com.gradle.plugin-publish) (see [docs.gradle.org](https://docs.gradle.org/current/userguide/publishing_gradle_plugins.html)).\n\nGiven that the `master` branch on the upstream repository is in the state from which you want to create a release, execute the following steps:\n\n**(1) Create release**\n\n[Create release via the GitHub UI](https://github.com/ePages-de/restdocs-api-spec/releases/new).\n\nUse the intended version number as \"Tag version\", e.g. \"0.18.2\".\nThis will automatically trigger a GitHub Action build which publishes the JAR files for this release to Sonatype.\n\n**(2) Login to Sonatype**\n\nLogin to Sonatype and navigate to the [staging repositories](https://oss.sonatype.org/#stagingRepositories).\n\n**(3) Close the staging repository**\n    \nSelect the generated staging repository and close it.\nCheck that there are no errors afterwards (e.g. missing signatures or Javadoc JARs).\n\n**(4) Release the repository**\n\nSelect the generated staging repository and release it.\nAfter few minutes, the release should be available in the [\"Public Repositories\" of ePages](https://oss.sonatype.org/service/local/repo_groups/public/content/com/epages/).\n\n**(5) Update documentation**\n\nCreate a new commit which updates the version numbers in the `README` file.\n","funding_links":[],"categories":["Kotlin","Uncategorized"],"sub_categories":["Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FePages-de%2Frestdocs-api-spec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FePages-de%2Frestdocs-api-spec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FePages-de%2Frestdocs-api-spec/lists"}