== Extension SPI

Swagger2Markup provides an Extension SPI to extend the functionality of Swagger2Markup. Five types of extension are available. An extension is an abstract class which must be implemented.

[options="header"]
.Swagger2Markup extensions
|====
| Name | Class | Description
| <<OverviewDocumentExtension>> | io.github.swagger2markup.spi.OverviewDocumentExtension | Can be used to extend the content of the Overview document
| <<PathsDocumentExtension>> | io.github.swagger2markup.spi.PathsDocumentExtension | Can be used to extend the content of the Paths document
| <<SecurityDocumentExtension>> | io.github.swagger2markup.spi.SecurityDocumentExtension | Can be used to extend the content of the Security document
| <<DefinitionsDocumentExtension>> | io.github.swagger2markup.spi.DefinitionsDocumentExtension | Can be used to extend the content of the Definitions document
| <<SwaggerModelExtension>> | io.github.swagger2markup.spi.SwaggerModelExtension | Can be used to modify the Swagger model before it is converted
|====

=== Creation of an extension

To create a custom extension, you have to create a class (e.g. `io.myname.MyExtension`) which extends an extension, e.g. `io.github.swagger2markup.spi.DefinitionsDocumentExtension`. Every extension point provides two methods which must be implemented: 

* `init`: This method is invoked once and can be used to initialize the extension.
* `apply`: This method is invoked multiple times depending on the type of the extension. The `Position` can be retrieved from the `Context` and can be used to extend the document at specific extension points.

[source,java,indent=0]
----
include::{coreProjectDir}/src/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 

Swagger2Markup extensions must be registered in the `Swagger2MarkupExtensionRegistry`. The default `Swagger2MarkupExtensionRegistry` of Swagger2Markup uses the `java.util.ServiceLoader` to load and register Swagger2Markup extensions automatically.

==== Automatic registration

To register your extension automatically, the following steps are required:

* Create a file called `META-INF/services/io.github.swagger2markup.spi.DefinitionsDocumentExtension` which contains your extensions’s full qualified name, e.g. `io.myname.MyExtension`.

*  When a `.jar` file containing your extension is added to the classpath of Swagger2Markup, the extensions will be automatically registered.

==== Manual registration

To register your extension manually, you have to use the `Swagger2MarkupExtensionRegistryBuilder`.

[source,java,indent=0]
----
include::{coreProjectDir}/src/test/java/io/github/swagger2markup/DocumentationTest.java[tags=swagger2MarkupExtensionRegistryBuilder]
----
1. Create a ``Swagger2MarkupExtensionRegistryBuilder`` using the default constructor
2. Register your custom extension
3. Build an instance of `Swagger2MarkupExtensionRegistry`
4. Use the custom Swagger2MarkupExtensionRegistry

=== Extensions points

==== OverviewDocumentExtension

The OverviewDocumentExtension allows to extend the overview document at positions :

* DOCUMENT_BEFORE: Before the document title (title level offset = 0)
* DOCUMENT_BEGIN: After the document title (title level offset = 1)
* DOCUMENT_END: At the end of the document (title level offset = 1)
* DOCUMENT_AFTER: At the very end of the document (title level offset = 0)

NOTE: Extension content titles must always start from level *1*. The title level will be adapted depending on position.

==== PathsDocumentExtension

The PathsDocumentExtension allows to extend the paths document at positions : 

* DOCUMENT_BEFORE: Before the document title (title level offset = 0)
* DOCUMENT_BEGIN: After the document title (title level offset = 1)
* OPERATION_BEFORE: Before each operation title (title level offset = 1)
* OPERATION_BEGIN: After each operation title (title level offset = 2)
* OPERATION_END: At the end of each operation (title level offset = 2)
* OPERATION_AFTER: At the very end of each operation (title level offset = 1)
* DOCUMENT_END: At the end of the document (title level offset = 1)
* DOCUMENT_AFTER: At the very end of the document (title level offset = 0)

Moreover, the PathsDocumentExtension allows to extend operation sections at positions :
  
* OPERATION_DESCRIPTION_BEFORE: Before each description section title (title level offset = 2)
* OPERATION_DESCRIPTION_BEGIN: After each description section title (title level offset = 3)
* OPERATION_DESCRIPTION_END: At the end of each description section (title level offset = 3)
* OPERATION_DESCRIPTION_AFTER: At the very end of each description section (title level offset = 2)

* OPERATION_PARAMETERS_BEFORE: Before each parameters section title (title level offset = 2)
* OPERATION_PARAMETERS_BEGIN: After each parameters section title (title level offset = 3)
* OPERATION_PARAMETERS_END: At the end of each parameters section (title level offset = 3)
* OPERATION_PARAMETERS_AFTER: At the very end of each parameters section (title level offset = 2)

* OPERATION_RESPONSES_BEFORE: Before each responses section title (title level offset = 2)
* OPERATION_RESPONSES_BEGIN: After each responses section title (title level offset = 3)
* OPERATION_RESPONSES_END: At the end of each responses section (title level offset = 3)
* OPERATION_RESPONSES_AFTER: At the very end of each responses section (title level offset = 2)

* OPERATION_SECURITY_BEFORE: Before each security section title (title level offset = 2)
* OPERATION_SECURITY_BEGIN: After each security section title (title level offset = 3)
* OPERATION_SECURITY_END: At the end of each security section (title level offset = 3)
* OPERATION_SECURITY_AFTER: At the very end of each security section (title level offset = 2)

NOTE: Extension content titles must always start from level *1*. The title level will be adapted depending on position.

==== SecurityDocumentExtension

The SecurityDocumentExtension allows to extend the security document at positions : 

* DOCUMENT_BEFORE: Before the document title (title level offset = 0)
* DOCUMENT_BEGIN: After the document title (title level offset = 1)
* SECURITY_SCHEME_BEFORE: Before each security scheme title (title level offset = 1)
* SECURITY_SCHEME_BEGIN: After each security scheme title (title level offset = 2)
* SECURITY_SCHEME_END: At the end of each security scheme (title level offset = 2)
* SECURITY_SCHEME_AFTER: At the very end of each security scheme (title level offset = 1)
* DOCUMENT_END: At the end of the document (title level offset = 1)
* DOCUMENT_AFTER: At the very end of the document (title level offset = 0)

NOTE: Extension content titles must always start from level *1*. The title level will be adapted depending on position.

==== DefinitionsDocumentExtension

The DefinitionsDocumentExtension allows to extend the definitions document at positions : 

* DOCUMENT_BEFORE: Before the document title (title level offset = 0)
* DOCUMENT_BEGIN: After the document title (title level offset = 1)
* DEFINITION_BEFORE: Before each definition title (title level offset = 1)
* DEFINITION_BEGIN: After each definition title (title level offset = 2)
* DEFINITION_END: At the end of each definition (title level offset = 2)
* DEFINITION_AFTER: At the very end of each definition (title level offset = 1)
* DOCUMENT_END: At the end of the document (title level offset = 1)
* DOCUMENT_AFTER: At the very end of the document (title level offset = 0)

NOTE: Extension content titles must always start from level *1*. The title level will be adapted depending on position.

==== SwaggerModelExtension

The SwaggerModelExtension allows to modify the Swagger model before it is processed by Swagger2Markup. For example, you could use this extension to delete Paths from the Swagger model which should not be rendered.

Example: 

[source,java,indent=0]
----
include::{coreProjectDir}/src/test/java/io/github/swagger2markup/builder/MySwaggerModelExtension.java[tags=MySwaggerModelExtension]
----
1. You can change any Swagger model property
2. You could even remove elements from the Swagger model

[[extension_commons_content_markup]]
=== Content markup language

Most content extensions supports to provide content in any markup language which will be *converted, if needed, to configured Swagger2Markup converter markup language* at import.

The content files markup language can be any https://github.com/Swagger2Markup/markup-document-builder[markup-document-builder] supported language : 

* ASCIIDOC : AsciiDoc. Mandatory content file extension : `adoc`

* MARKDOWN : Github Flavored Markdown. Mandatory content file extension : `md`

* CONFLUENCE_MARKUP : Confluence Wiki markup. Mandatory content file extension : `txt`

[IMPORTANT]
====
Currently supported conversions are :

* Markdown -> AsciiDoc
====

=== Provided Extensions

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
| <<extension_import_files,Dynamic file import extension>> | Allows to dynamically import Markup from files.
| <<extension_spring_restdocs,Spring RestDocs extension>> | Allows to import Curl, HTTP request and response snippets from https://github.com/spring-projects/spring-restdocs[Spring Rest Docs].
| <<extension_import_schemas,Schema file import extension>> | Allows to import JSON or XML Schema files.
|====

include::extensions/import_files.adoc[leveloffset=+2]

include::extensions/spring_restdocs.adoc[leveloffset=+2]

include::extensions/import_schemas.adoc[leveloffset=+2]