diff --git a/src/docs/asciidoc/extension_spi.adoc b/src/docs/asciidoc/extension_spi.adoc index 079bccd8..71587eea 100644 --- a/src/docs/asciidoc/extension_spi.adoc +++ b/src/docs/asciidoc/extension_spi.adoc @@ -3,7 +3,7 @@ Swagger2Markup provides an Extension SPI to extend the functionality of Swagger2Markup. Five types of extension points are available. Each extension point is an abstract class which must be implemented. [options="header"] -.Swagger2Markup Extensions points +.Swagger2Markup extensions points |==== | Name | Class | Description | ``OverviewDocumentExtension`` | io.github.swagger2markup.spi.OverviewDocumentExtension | Can be used to extend the content of the Overview document @@ -24,6 +24,10 @@ To create a custom extension, you have to create a class (e.g. `io.myname.MyExte ---- include::../../test/java/io/github/swagger2markup/builder/MyExtension.java[tags=MyExtension] ---- +1. You can retrieve extension properties from the config to configure the extension. +2. You can retrieve a `MarkupDocBuilder` from the `Context`. +3. You can retrieve the current `Position` from the Context. +4. You can use a `MarkupDocBuilder` to add Markup using a fluent API or import Markup from files. === Registration of an extension @@ -112,9 +116,136 @@ The SwaggerModelExtension allows to modify the Swagger model before it is proces === Provided Extensions -Swagger2Markup provides some extensions which can be used out-of-the-box. +Swagger2Markup provides some extensions which can be used out-of-the-box. You just have to add the extension to your classpath. + +[options="header"] +.Swagger2Markup extensions +|==== +| Name | Description +| <> | Allows to dynamically import Markup from files. +| <> | Allows to import example Curl, HTTP request and response snippets from Spring Rest Docs. +| <> | Allows to import JSON or XML Schema files. +|==== + +==== Dynamic file import extension + +===== Usage guide + +[source,groovy, subs="attributes"] +---- +repositories { + jCenter() +} + +compile "io.github.swagger2markup:swagger2markup-import-files-ext:{project-version}" +---- + +The extension searches for markup files in configurable paths to append the markup to the documents. The markup files must conform to a naming convention to be found. The files must start with the position where the document should be extended and end with the markup file extension (e.g `adoc` or `md`). See documentation of <>. + +All documents: + +* `document-before-*.` +* `document-after-*.` +* `document-begin-*.` +* `document-end-*.` + +Paths document: + +* `operation-begin-*.` +* `operation-end-*.` + +Definitions and Security document: + +* `defintion-begin-*.` +* `defintion-begin-*.` + +===== Configuration + +The extension adds the following properties to Swagger2Markup which must be configured: + +[options="header"] +.Extension properties +|==== +| Name | Description | Example +| `swagger2markup.extensions.dynamicOverview.contentPath` | The path to the files which should be imported into the Overview document | `src/test/resources/docs/asciidoc/overview` +| `swagger2markup.extensions.dynamicDefinitions.contentPath` | The path to the files which should be imported into the Definitions document | `src/test/resources/docs/asciidoc/definitions` +| `swagger2markup.extensions.dynamicPaths.contentPath` | The path to the files which should be imported into the Paths document | `src/test/resources/docs/asciidoc/paths` +| `swagger2markup.extensions.dynamicSecurity.contentPath` | TThe path to the files which should be imported into the Security document | `src/test/resources/docs/asciidoc/security` +|==== + +==== Spring RestDocs extension + +===== Usage guide + +[source,groovy, subs="attributes"] +---- +repositories { + jCenter() +} + +compile "io.github.swagger2markup:swagger2markup-spring-restdocs-ext:{project-version}" +---- + +The extension searches for Spring RestDocs snippet files in a configurable path to append the snippets at the end of a path operation section. The snippet files must be called: + +* http-request.` +* http-response.` +* curl-request.` + +The files must be stored in a folder which matches the Swagger operationId. + +Swagger Example: + +[source] +---- +paths: + /pets: + post: + summary: Add a new pet to the store + operationId: addPet + ... +---- + +Example: `/snippets/addPet/http-request.adoc`. + +===== Configuration + +The extension adds the following properties to Swagger2Markup which must be configured: + +[options="header"] +.Extension properties +|==== +| Name | Description | Example +| `swagger2markup.extensions.springRestDocs.snippetBaseUri` | The path to the Spring RestDocs snippets | `src/test/resources/docs/asciidoc/paths` +|==== + +==== Schema file import extension + +===== Usage guide + +[source,groovy, subs="attributes"] +---- +repositories { + jCenter() +} + +compile "io.github.swagger2markup:swagger2markup-import-schemas-ext:{project-version}" +---- + +The extension searches for Schema files in a configurable path to append the Schema file content at the end of a definition section. The Schema files must conform to a naming convention to be found. The files must be called `schema.xsd` or `schema.json` and must be stored in a folder which matches the name of a definition. + +Example: `/schemas/Pet/schema.json`. + + +===== Configuration + +The extension adds the following properties to Swagger2Markup which must be configured: + +[options="header"] +.Extension properties +|==== +| Name | Description | Example +| `swagger2markup.extensions.schema.schemaBaseUri` | The path to the schema files | `src/test/resources/docs/asciidoc/schemas` +|==== -1. An extension which allows to dynamically import Markup from files. -2. An extension which allows to import example Curl, HTTP request and response snippets from Spring Rest Docs. -3. An extension which allows to import JSON or XML Schema files. diff --git a/src/test/java/io/github/swagger2markup/builder/MyExtension.java b/src/test/java/io/github/swagger2markup/builder/MyExtension.java index 391612a1..91e8fea6 100644 --- a/src/test/java/io/github/swagger2markup/builder/MyExtension.java +++ b/src/test/java/io/github/swagger2markup/builder/MyExtension.java @@ -18,10 +18,13 @@ package io.github.swagger2markup.builder; import io.github.swagger2markup.Swagger2MarkupConverter; import io.github.swagger2markup.Swagger2MarkupProperties; import io.github.swagger2markup.markup.builder.MarkupDocBuilder; +import io.github.swagger2markup.markup.builder.MarkupLanguage; import io.github.swagger2markup.spi.DefinitionsDocumentExtension; import io.swagger.models.Model; import io.swagger.models.Swagger; +import java.io.StringReader; + // tag::MyExtension[] public class MyExtension extends DefinitionsDocumentExtension { @@ -31,18 +34,24 @@ public class MyExtension extends DefinitionsDocumentExtension { @Override public void init(Swagger2MarkupConverter.Context globalContext) { // init is executed once - Swagger2MarkupProperties extensionProperties = globalContext.getConfig().getExtensionsProperties(); + Swagger2MarkupProperties extensionProperties = globalContext.getConfig().getExtensionsProperties(); //<1> extensionProperty = extensionProperties.getRequiredString(EXTENSION_ID + ".propertyName"); Swagger model = globalContext.getSwagger(); } @Override public void apply(Context context) { - MarkupDocBuilder markupBuilder = context.getMarkupDocBuilder(); - Position position = context.getPosition(); + MarkupDocBuilder markupBuilder = context.getMarkupDocBuilder(); //<2> + Position position = context.getPosition(); //<3> String definitionName = context.getDefinitionName().get(); Model definitionModel = context.getModel().get(); + if(position.equals(Position.DEFINITION_END)) { + markupBuilder.sectionTitleLevel4(definitionName) //<4> + .paragraph(definitionModel.getDescription()) + .importMarkup(new StringReader("*Markup*"), MarkupLanguage.ASCIIDOC); + } + // apply is executed per definition } }