Repository: syncope Updated Branches: refs/heads/master 39f7f7ebf -> c4587cfdf
[SYNCOPE-700] Extensions Project: http://git-wip-us.apache.org/repos/asf/syncope/repo Commit: http://git-wip-us.apache.org/repos/asf/syncope/commit/dcfbf6f0 Tree: http://git-wip-us.apache.org/repos/asf/syncope/tree/dcfbf6f0 Diff: http://git-wip-us.apache.org/repos/asf/syncope/diff/dcfbf6f0 Branch: refs/heads/master Commit: dcfbf6f0efaf06f74e063f2d0007c747c50c129f Parents: 39f7f7e Author: Francesco Chicchiriccò <[email protected]> Authored: Wed Aug 24 16:12:02 2016 +0200 Committer: Francesco Chicchiriccò <[email protected]> Committed: Wed Aug 24 16:12:02 2016 +0200 ---------------------------------------------------------------------- src/main/asciidoc/images/swaggerLoggerRead.png | Bin 98491 -> 0 bytes .../reference-guide/architecture/core.adoc | 2 +- .../reference-guide/concepts/concepts.adoc | 2 + .../reference-guide/concepts/extensions.adoc | 92 +++++++++++++++++++ .../reference-guide/extensions/extensions.adoc | 60 ------------ .../reference-guide/reference-guide.adoc | 2 - 6 files changed, 95 insertions(+), 63 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/syncope/blob/dcfbf6f0/src/main/asciidoc/images/swaggerLoggerRead.png ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/images/swaggerLoggerRead.png b/src/main/asciidoc/images/swaggerLoggerRead.png deleted file mode 100644 index 0861665..0000000 Binary files a/src/main/asciidoc/images/swaggerLoggerRead.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/syncope/blob/dcfbf6f0/src/main/asciidoc/reference-guide/architecture/core.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/architecture/core.adoc b/src/main/asciidoc/reference-guide/architecture/core.adoc index 8cf0324..7252da3 100644 --- a/src/main/asciidoc/reference-guide/architecture/core.adoc +++ b/src/main/asciidoc/reference-guide/architecture/core.adoc @@ -32,7 +32,7 @@ This interface enables third-party applications, written in any programming lang The rich pre-defined set of endpoints can be extended by adding new ones, which might be needed on a given Apache Syncope deployment to complement the native features with domain-specific operations. -An <<swagger-ui,extension>> is available, providing full http://swagger.io/[Swagger^] features, +An <<swagger,extension>> is available, providing full http://swagger.io/[Swagger^] features, which enables in-browser access to all the REST endpoints defined. At a technical level, the RESTful interface is a fully-compliant http://git-wip-us.apache.org/repos/asf/syncope/blob/dcfbf6f0/src/main/asciidoc/reference-guide/concepts/concepts.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/concepts/concepts.adoc b/src/main/asciidoc/reference-guide/concepts/concepts.adoc index c6f5e15..8aff5b7 100644 --- a/src/main/asciidoc/reference-guide/concepts/concepts.adoc +++ b/src/main/asciidoc/reference-guide/concepts/concepts.adoc @@ -45,3 +45,5 @@ include::reports.adoc[] include::audit.adoc[] include::domains.adoc[] + +include::extensions.adoc[] http://git-wip-us.apache.org/repos/asf/syncope/blob/dcfbf6f0/src/main/asciidoc/reference-guide/concepts/extensions.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/concepts/extensions.adoc b/src/main/asciidoc/reference-guide/concepts/extensions.adoc new file mode 100644 index 0000000..591dbc9 --- /dev/null +++ b/src/main/asciidoc/reference-guide/concepts/extensions.adoc @@ -0,0 +1,92 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. +// +=== Extensions + +Extensions allow to optionally enrich the _vanilla_ Apache Syncope with useful features, without the need of bloating +every single deployment with non-needed libraries and configurations. + +With reference to <<architecture,architecture>>, an extension might add a <<rest>> endpoint, manage the +<<persistence,persistence>> of additional entities, extend the <<security,security>> mechanisms, tweak the +<<provisioning-layer,provisioning layer>>, add features to the <<admin-console-component,admin console>>, or even bring +all such things together. + +Extensions are available from different sources: + +. as Maven artifacts published from the Apache Syncope codebase, part of the official releases - this is the case of the +ones detailed below; +. as Maven artifacts published by third parties; +. as part of a given deployment sources, as explained <<customization-extensions, in the following>>. + +==== Apache Camel Provisioning Engine + +This extension delegates the <<provisioning,provisioning>> process execution to a set of +http://camel.apache.org[Apache Camel^] routes. + +The pre-loaded routes can be dynamically changed at runtime via REST or admin console, and modifications are immediately +made available for processing. + +For example, on creating a new user, you may wish to send an email to an administrator; or if a user is +reactivated, you may wish to reactivate the user's home page on a web server. + +All these things and more are possible using the myriad of +http://camel.apache.org/components.html[components^] that are available to be used in Apache Camel routes. + +[NOTE] +.Extension Sources +==== +The sources of this extension are available from the Apache Syncope +ifeval::["{snapshotOrRelease}" == "release"] +https://github.com/apache/syncope/tree/syncope-{docVersion}/ext/camel[source tree^] +endif::[] +ifeval::["{snapshotOrRelease}" == "snapshot"] +https://github.com/apache/syncope/tree/master/ext/camel[source tree^] +endif::[] +. +==== + +[TIP] +==== +This extension is adding features to all components and layers available and can be taken as reference when creating +<<customization-extensions,new extensions>>. +==== + +==== Swagger + +This extension enables http://swagger.io/swagger-ui/[Swagger UI^] as web interface for dealing with Apache Syncope +<<rest,RESTful>> services. + +Once installed, Swagger UI is available at +[source] +-- +http://host:port/syncope/swagger/ +-- + +where `host` and `port` reflect your Java EE container installation. + +[NOTE] +.Extension Sources +==== +The sources of this extension are available from the Apache Syncope +ifeval::["{snapshotOrRelease}" == "release"] +https://github.com/apache/syncope/tree/syncope-{docVersion}/ext/swagger-ui[source tree^] +endif::[] +ifeval::["{snapshotOrRelease}" == "snapshot"] +https://github.com/apache/syncope/tree/master/ext/swagger-ui[source tree^] +endif::[] +. +==== http://git-wip-us.apache.org/repos/asf/syncope/blob/dcfbf6f0/src/main/asciidoc/reference-guide/extensions/extensions.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/extensions/extensions.adoc b/src/main/asciidoc/reference-guide/extensions/extensions.adoc deleted file mode 100644 index 40e2be3..0000000 --- a/src/main/asciidoc/reference-guide/extensions/extensions.adoc +++ /dev/null @@ -1,60 +0,0 @@ -// -// Licensed to the Apache Software Foundation (ASF) under one -// or more contributor license agreements. See the NOTICE file -// distributed with this work for additional information -// regarding copyright ownership. The ASF licenses this file -// to you under the Apache License, Version 2.0 (the -// "License"); you may not use this file except in compliance -// with the License. You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, -// software distributed under the License is distributed on an -// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -// KIND, either express or implied. See the License for the -// specific language governing permissions and limitations -// under the License. -// -== Extensions - -=== Apache Camel Provisioning Engine - -=== Swagger UI - -The Swagger installation is really simple because you just add the Maven dependency to your core pom.xml file generated -from the archetype operation; the dependency is: -[source, xml] ----- -<dependency> - <groupId>org.apache.syncope.ext</groupId> - <artifactId>syncope-ext-swagger-ui</artifactId> - <version>${syncope.version}</version> -</dependency> ----- - -The swagger interface is available going to the URL -[source] --- -http://localhost:9080/syncope/swagger/#/ --- - -Reading from the Swagger http://swagger.io/[website] - -.Swagger -**** -Swagger is a simple yet powerful representation of your RESTful API. With the largest ecosystem of API tooling on -the planet, thousands of developers are supporting Swagger in almost every modern programming language and deployment -environment. With a Swagger-enabled API, you get interactive documentation, client SDK generation and discoverability. - -We created Swagger to help fulfill the promise of APIs. Swagger helps companies like Apigee, Getty Images, Intuit, -LivingSocial, McKesson, Microsoft, Morningstar, and PayPal build the best possible services with RESTful APIs. - -Now in version 2.0, Swagger is more enabling than ever. And it's 100% open source software. - -**** - -To be consistent with the example, below the image shows the Swagger UI used to read the configuration -of _org.apache.syncope.core.rest_ - -image::swaggerLoggerRead.png[swaggerLoggerRead] \ No newline at end of file http://git-wip-us.apache.org/repos/asf/syncope/blob/dcfbf6f0/src/main/asciidoc/reference-guide/reference-guide.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/reference-guide.adoc b/src/main/asciidoc/reference-guide/reference-guide.adoc index e0f4c53..fd448ed 100644 --- a/src/main/asciidoc/reference-guide/reference-guide.adoc +++ b/src/main/asciidoc/reference-guide/reference-guide.adoc @@ -81,5 +81,3 @@ include::architecture/architecture.adoc[] include::concepts/concepts.adoc[] include::workingwithapachesyncope/workingwithapachesyncope.adoc[] - -include::extensions/extensions.adoc[]
