From bf0c7e240f8e19c36f341c3b5ab52a072297aa57 Mon Sep 17 00:00:00 2001 From: Michael Vorburger Date: Wed, 18 Nov 2020 22:50:17 +0100 Subject: [PATCH] docs: Fix broken build --- .../client/test/FineractClientDemo.java | 45 +++++++++++++++++++ fineract-doc/build.gradle | 3 ++ fineract-doc/src/docs/en/02_architecture.adoc | 6 +-- fineract-doc/src/docs/en/05_client.adoc | 9 ++-- 4 files changed, 54 insertions(+), 9 deletions(-) create mode 100644 fineract-client/src/test/java/org/apache/fineract/client/test/FineractClientDemo.java diff --git a/fineract-client/src/test/java/org/apache/fineract/client/test/FineractClientDemo.java b/fineract-client/src/test/java/org/apache/fineract/client/test/FineractClientDemo.java new file mode 100644 index 000000000..316240bb4 --- /dev/null +++ b/fineract-client/src/test/java/org/apache/fineract/client/test/FineractClientDemo.java @@ -0,0 +1,45 @@ +/** + * 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. + */ +package org.apache.fineract.client.test; + +import java.util.List; +import org.apache.fineract.client.models.RetrieveOneResponse; +import org.apache.fineract.client.util.Calls; +import org.apache.fineract.client.util.FineractClient; + +/** + * Demo code which is included in the fineract-doc/src/docs/en/05_client.adoc. + * + * This is not a real running integration test - those are in + * integration-tests/src/test/java/org/apache/fineract/integrationtests/client. + * + * @author Michael Vorburger.ch + */ +public class FineractClientDemo { + + void demoClient() { + // tag::documentation[] + FineractClient fineract = FineractClient.builder().baseURL("https://demo.fineract.dev/fineract-provider/api/v1/").tenant("default") + .basicAuth("mifos", "password").build(); + List staff = Calls.ok(fineract.staff.retrieveAll16(1L, true, false, "ACTIVE")); + String name = staff.get(0).getDisplayName(); + // end::documentation[] + } + +} diff --git a/fineract-doc/build.gradle b/fineract-doc/build.gradle index 82dfb475b..78c12727e 100644 --- a/fineract-doc/build.gradle +++ b/fineract-doc/build.gradle @@ -62,6 +62,9 @@ asciidoctorj { epub.version '1.5.0-alpha.18' revealjs.version '4.0.1' } + + fatalWarnings ~/include file not found|missing callout|image to embed not found or not readable/ + fatalWarnings missingIncludes() } asciidoctor { diff --git a/fineract-doc/src/docs/en/02_architecture.adoc b/fineract-doc/src/docs/en/02_architecture.adoc index 9a9e63a6a..837cbb404 100644 --- a/fineract-doc/src/docs/en/02_architecture.adoc +++ b/fineract-doc/src/docs/en/02_architecture.adoc @@ -33,7 +33,7 @@ Mifos was an idea born out of a wish to create and deploy technology that allows === System Overview .Platform System Overview -image::images/platform-systemview.png[] +image::platform-systemview.png[] Financial institutions deliver their services to customers through a variety of means today. @@ -53,7 +53,7 @@ The platform is the core engine of the MIS. It hides alot of the complexity that As ALL capabilities of the platform are exposed through an API, The API docs are the best place to view a detailed breakdown of what the platform does. See online API Documentation. .Platform Functional Overview -image::images/platform-categories.png[] +image::platform-categories.png[] At a higher level though we see the capabilities fall into the following categories: @@ -170,7 +170,7 @@ Within each vertical slice is some common packaging structure: NOTE: The implementation of the platform code to process commands through handlers whilst supporting maker-checker and authorisation checks is a little bit convoluted at present and is an area pin-pointed for clean up to make it easier to on board new platform developers. In the mean time below content is used to explain its workings at present. .CQRS -image::images/command-query.png[] +image::command-query.png[] Taking into account example shown above for the *users* resource. diff --git a/fineract-doc/src/docs/en/05_client.adoc b/fineract-doc/src/docs/en/05_client.adoc index a4f6d0254..6b8c06ffd 100644 --- a/fineract-doc/src/docs/en/05_client.adoc +++ b/fineract-doc/src/docs/en/05_client.adoc @@ -6,17 +6,14 @@ Apache Fineract supports client code generation using https://openapi-generator. The `fineract-client.jar` will eventually be available on Maven Central (watch https://issues.apache.org/jira/browse/FINERACT-1102[FINERACT-1102]). Until it is, you can quite easily build the latest and greatest version locally from source, see below. -The https://github.com/apache/fineract/search?q=FineractClient.java[`FineractClient`] is the entry point to the _Fineract SDK Java API Client_. https://github.com/apache/fineract/search?q=Calls.java[`Calls`] is a convenient and recommended utility to simplify the use of the https://square.github.io/retrofit/2.x/retrofit/retrofit2/Call.html[`retrofit2.Call`] type which all API operations return. Their benefit is illustrated e.g. in the https://github.com/apache/fineract/search?q=FineractClientTest.java[`FineractClientTest`], but in short: +The https://github.com/apache/fineract/search?q=FineractClient.java[`FineractClient`] is the entry point to the _Fineract SDK Java API Client_. https://github.com/apache/fineract/search?q=Calls.java[`Calls`] is a convenient and recommended utility to simplify the use of the https://square.github.io/retrofit/2.x/retrofit/retrofit2/Call.html[`retrofit2.Call`] type which all API operations return. This permits you to use the API like the https://github.com/apache/fineract/search?q=FineractClientDemo.java[`FineractClientDemo`] illustrates: [source,java] -// /home/spaddo/workspace/fineract/vidakovic-fineract-develop/ ---- import org.apache.fineract.client.util.FineractClient; import static org.apache.fineract.client.util.Calls.ok; -include::{rootdir}/fineract-client/src/test/java/org/apache/fineract/client/test/FineractClientTest.java[lines=44..45] - -System.out.println(ok(fineract.clients.retrieveAll(...).getTotalFilteredRecords()); +include::{rootdir}/fineract-client/src/test/java/org/apache/fineract/client/test/FineractClientDemo.java[tags=documentation] ---- === Generate API Client @@ -31,4 +28,4 @@ If you need to save time to incrementally work on making small changes to Swagge === Validate OpenAPI Spec File -The `resolve` task in https://github.com/apache/fineract/blob/develop/fineract-provider/build.gradle#L80[build.gradle] file will generate the OpenAPI Spec File for the project. To make sure Swagger Codegen generates a correct library, it is important for the OpenAPI Spec file to be valid. Validation is done automatically by the OpenAPI code generator Gradle plugin. If you still have problems during code generation please use https://validator.swagger.io/[Swagger OpenAPI Validator] to validate the spec file. \ No newline at end of file +The `resolve` task in https://github.com/apache/fineract/blob/develop/fineract-provider/build.gradle#L80[build.gradle] file will generate the OpenAPI Spec File for the project. To make sure Swagger Codegen generates a correct library, it is important for the OpenAPI Spec file to be valid. Validation is done automatically by the OpenAPI code generator Gradle plugin. If you still have problems during code generation please use https://validator.swagger.io/[Swagger OpenAPI Validator] to validate the spec file.