Skip to content

Commit 7943c7a

Browse files
hleb-albauhleb-albau
authored
documentation as static offline html file (#28)
1 parent aeaaba6 commit 7943c7a

14 files changed

+221
-23
lines changed

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,2 @@
1-
.idea
1+
.idea
2+
document-reader-static-doc.html

‎README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,3 +24,12 @@
2424
```
2525
docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli validate --recommend -i /local/index.yml
2626
```
27+
28+
## Building Redoc single page html documentation
29+
Edit **rt.yml** - remove **components.schemas.ResultItem.discriminator** node and run next command
30+
```
31+
npx redoc-cli bundle index.yml --output document-reader-static-doc.html \
32+
--options.maxDisplayedEnumValues=5 --options.theme.logo.gutter="20px" \
33+
--options.theme.colors.primary.main="#8a53cb" --options.expandResponses="all" \
34+
--options.expandSingleSchemaField --options.hideDownloadButton --options.jsonSampleExpandLevel="6"
35+
```

‎common.yml‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ components:
1818

1919
CheckResult:
2020
type: integer
21+
description: "0 - result is negative; 1 - result is positive; 2 - сheck was not performed"
2122
enum:
2223
- 0
2324
- 1
@@ -86,9 +87,10 @@ components:
8687
description: "Base64 encoded image"
8788
type: string
8889
format: byte
90+
example: "Base64 encoded image"
8991

9092
RectangleCoordinates:
91-
description: "Coordinates of the rectangle region in the normalized image of the document"
93+
description: "Coordinates of the rectangle region on a document image(result type 1). Represented by two points - (left, top) + (right, bottom)"
9294
type: object
9395
required:
9496
- left
@@ -107,7 +109,7 @@ components:
107109

108110
RfidLocation:
109111
type: integer
110-
description: "Determines the presence and location of an RFID chip in a document"
112+
description: "Determines the presence and location of an RFID chip in a document. 0 - no rfid chip; 1 - chip is located in the document data page; 2 - chip is located in the back page or inlay of the document"
111113
enum:
112114
- 0
113115
- 1

‎index.yml‎

Lines changed: 68 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,18 @@
11
openapi: 3.0.3
22
info:
3-
version: 5.2.0
3+
version: 5.3.0
44
title: Regula Document Reader Web API
5-
description: Regula Document Reader Web API
5+
x-logo:
6+
url: 'https://regulaforensics.com/bitrix/media/img/elements/logo.png'
7+
href: 'https://mobile.regulaforensics.com/'
8+
description: |
9+
Documents recognition as easy as reading two bytes.
10+
11+
# Clients:
12+
* [JavaScript](https://github.com/regulaforensics/DocumentReader-web-js-client) client for the browser and node.js based on axios
13+
* [Java](https://github.com/regulaforensics/DocumentReader-web-java-client) client compatible with jvm and android
14+
* [Python](https://github.com/regulaforensics/DocumentReader-web-python-client) 3.5+ client
15+
* [C#](https://github.com/regulaforensics/DocumentReader-web-csharp-client) client for .NET & .NET Core
616
717
servers:
818
- url: http://localhost:8080/
@@ -12,8 +22,63 @@ servers:
1222
- url: https://test-api.regulaforensics.com/
1323
description: Regula document reader test SaaS
1424

25+
1526
paths:
1627
/api/process:
1728
$ref: './p-process.yml#/paths/~1process'
1829
/api/ping:
19-
$ref: './p-ping.yml#/paths/~1ping'
30+
$ref: './p-ping.yml#/paths/~1ping'
31+
32+
tags:
33+
- name: process
34+
description: Everything about perfoming request and parsing response
35+
- name: status_model
36+
x-displayName: Status Model
37+
description: |
38+
<SchemaDefinition schemaRef="#/components/schemas/Status" />
39+
- name: text_model
40+
x-displayName: Text Model
41+
description: |
42+
<SchemaDefinition schemaRef="#/components/schemas/Text" />
43+
- name: images_model
44+
x-displayName: Images Model
45+
description: |
46+
**Images model:**
47+
<SchemaDefinition schemaRef="#/components/schemas/Images" />
48+
**Document image model:**
49+
<SchemaDefinition schemaRef="#/components/schemas/DocumentImage" />
50+
- name: document_model
51+
x-displayName: Document Model
52+
description: |
53+
**Choosen Document model:**
54+
<SchemaDefinition schemaRef="#/components/schemas/ChosenDocumentType" />
55+
**Candidates model:**
56+
<SchemaDefinition schemaRef="#/components/schemas/DocumentTypesCandidates" />
57+
58+
x-tagGroups:
59+
- name: Requests
60+
tags:
61+
- process
62+
- name: Models
63+
tags:
64+
- status_model
65+
- text_model
66+
- images_model
67+
- document_model
68+
69+
components:
70+
schemas:
71+
Status:
72+
$ref: "./rt-status.yml#/components/schemas/Status"
73+
Text:
74+
$ref: "./rt-text.yml#/components/schemas/Text"
75+
Images:
76+
$ref: "./rt-images.yml#/components/schemas/Images"
77+
DocumentImage:
78+
$ref: "./common.yml#/components/schemas/ImageData"
79+
DocumentTypesCandidates:
80+
$ref: "./rt-doc-type-old.yml#/components/schemas/DocumentTypesCandidatesList"
81+
ChosenDocumentType:
82+
$ref: "./rt-doc-type-old.yml#/components/schemas/OneCandidate"
83+
DocumentType:
84+
$ref: "./e-document-type.yml#/components/schemas/DocumentType"

‎p-process.yml‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ paths:
55
post:
66
summary: Process list of documents images and return extracted data
77
operationId: api-process
8+
tags:
9+
- process
810
requestBody:
911
content:
1012
application/json:
@@ -22,6 +24,112 @@ paths:
2224
description: "Bad request. Check your input data."
2325
"403":
2426
description: "Bad license. Either server or request does not contain valid license."
27+
x-codeSamples:
28+
- lang: 'JavaScript'
29+
source: |
30+
import {DocumentReaderApi, FieldType, GraphicFieldType} from '@regulaforensics/document-reader-webclient/esm'
31+
const {DOCUMENT_NUMBER, SURNAME_AND_GIVEN_NAMES, DATE_OF_BIRTH} = FieldType;
32+
const {PORTRAIT, SIGNATURE} = GraphicFieldType;
33+
34+
const imageAsBase64String = getDocImageAsBase64String()
35+
const api = new DocumentReaderApi({basePath: "http://localhost:8080"});
36+
const result = await api.process(imageAsBase64String)
37+
38+
// text fields
39+
const docNumber = result.getTextField(DOCUMENT_NUMBER)
40+
const fullName = result.getTextField(SURNAME_AND_GIVEN_NAMES)
41+
const dateOfBirth = result.getTextField(DATE_OF_BIRTH)
42+
43+
// graphics fields
44+
const portraitAsBase64 = result.getGraphicsField(PORTRAIT)
45+
const signatureAsBase64 = result.getGraphicsField(SIGNATURE)
46+
- lang: 'Java'
47+
source: |
48+
byte[] imageBytes = readFile("australia_passport.jpg");
49+
var image = new ProcessRequestImage(imageBytes, Light.WHITE);
50+
51+
var requestParams = new RecognitionParams()
52+
.withScenario(Scenario.FULL_PROCESS)
53+
.withResultTypeOutput(Result.STATUS, Result.TEXT, Result.IMAGES);
54+
55+
RecognitionRequest request = new RecognitionRequest(requestParams, List.of(image));
56+
57+
var api = new DocumentReaderApi();
58+
RecognitionResponse response = api.process(request);
59+
60+
var status = response.status();
61+
var docOverallStatus = status.getComplete() == CheckResult.OK ? "valid" : "not valid";
62+
var docOpticalTextStatus = status.getDetailsOptical().getText();
63+
64+
var docNumberField = response.text().getField(DOCUMENT_NUMBER);
65+
var docNumberMrz = docNumberField.getValue(Source.MRZ);
66+
var docNumberMrzValidity = docNumberField.sourceValidity(Source.MRZ);
67+
var docNumberMrzVisualMatching = docNumberField.crossSourceComparison(Source.MRZ, Source.VISUAL);
68+
- lang: 'Python'
69+
source: |
70+
from regula.documentreader.webclient import *
71+
72+
with open("australia_passport.jpg", "rb") as f:
73+
input_image = f.read()
74+
75+
with DocumentReaderApi(host='http://localhost:8080') as api:
76+
params = ProcessParams(
77+
scenario=Scenario.FULL_PROCESS,
78+
result_type_output=[Result.DOCUMENT_IMAGE, Result.STATUS, Result.TEXT, Result.IMAGES]
79+
)
80+
request = RecognitionRequest(process_params=params, images=[input_image])
81+
response = api.process(request)
82+
83+
# status examples
84+
response_status = response.status
85+
doc_overall_status = "valid" if response_status.overall_status == CheckResult.OK else "not valid"
86+
87+
# text fields example
88+
doc_number_field = response.text.get_field(TextFieldType.DOCUMENT_NUMBER)
89+
doc_number_mrz = doc_number_field.get_value()
90+
doc_number_visual = doc_number_field.get_value(Source.VISUAL)
91+
doc_number_visual_validity = doc_number_field.source_validity(Source.VISUAL)
92+
doc_number_mrz_validity = doc_number_field.source_validity(Source.MRZ)
93+
doc_number_mrz_visual_matching = doc_number_field.cross_source_comparison(Source.MRZ, Source.VISUAL)
94+
95+
# images fields example
96+
normalized_input_image = response.images.document_image()
97+
portrait_field = response.images.get_field(GraphicFieldType.PORTRAIT)
98+
portrait_from_visual = portrait_field.get_value(Source.VISUAL)
99+
portrait_from_rfid = portrait_field.get_value(Source.RFID, original=True)
100+
- lang: 'C#'
101+
source: |
102+
var imageBytes = File.ReadAllBytes("australia_passport.jpg");
103+
var image = new ProcessRequestImage(new ImageData(imageBytes), Light.WHITE);
104+
105+
var requestParams = new RecognitionParams()
106+
.WithScenario(Scenario.FULL_PROCESS)
107+
.WithResultTypeOutput(new List<int> { Result.STATUS, Result.TEXT, Result.IMAGES, Result.DOCUMENT_TYPE });
108+
var request = new RecognitionRequest(requestParams, image);
109+
110+
var api = licenseFromEnv != null
111+
? new DocumentReaderApi(apiBaseUrl).WithLicense(licenseFromEnv)
112+
: new DocumentReaderApi(apiBaseUrl).WithLicense(licenseFromFile);
113+
var response = api.Process(request);
114+
115+
// status examples
116+
var status = response.Status();
117+
string docOverallStatus = status.OverallStatus == CheckResult.OK ? "valid" : "not valid";
118+
string docOpticalTextStatus = status.DetailsOptical.Text == CheckResult.OK ? "valid" : "not valid";
119+
120+
// text fields examples
121+
var docNumberField = response.Text().GetField(TextFieldType.DOCUMENT_NUMBER);
122+
string docNumberVisual = docNumberField.GetValue(Source.VISUAL);
123+
string docNumberMrz = docNumberField.GetValue(Source.MRZ);
124+
int docNumberVisualValidity = docNumberField.SourceValidity(Source.VISUAL);
125+
int docNumberMrzValidity = docNumberField.SourceValidity(Source.MRZ);
126+
int docNumberMrzVisualMatching = docNumberField.CrossSourceComparison(Source.MRZ, Source.VISUAL);
127+
128+
// images fields examples
129+
var documentImage = response.Images().GetField(GraphicFieldType.DOCUMENT_FRONT).GetValue();
130+
var portraitField = response.Images().GetField(GraphicFieldType.PORTRAIT);
131+
var portraitFromVisual = portraitField.GetValue(Source.VISUAL);
132+
25133
26134
components:
27135
schemas:

‎rt-doc-type-old.yml‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,22 +3,25 @@ components:
33
schemas:
44

55
ChosenDocumentTypeResult:
6+
title: "Chosen Document Type"
67
description: "Contains information about the type of document that was determined
78
based on the analysis of the provided image"
89
allOf:
9-
- $ref: './rt.yml#/components/schemas/ResultItem'
1010
- type: object
1111
properties:
1212
OneCandidate:
1313
$ref: "#/components/schemas/OneCandidate"
14+
- $ref: './rt.yml#/components/schemas/ResultItem'
1415

1516
DocumentTypesCandidatesResult:
17+
title: "Document Types Candidates"
1618
allOf:
17-
- $ref: './rt.yml#/components/schemas/ResultItem'
1819
- type: object
1920
properties:
2021
CandidatesList:
2122
$ref: "#/components/schemas/DocumentTypesCandidatesList"
23+
- $ref: './rt.yml#/components/schemas/ResultItem'
24+
2225

2326
DocumentTypesCandidatesList:
2427
type: object

‎rt-image-data.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,18 @@ components:
33
schemas:
44

55
GraphicsResult:
6+
title: "Graphics (deprecated)"
67
description: "Graphic fields extracted from one of the document sources.
78
Returns separate results for each provided page."
89
required:
910
- DocGraphicsInfo
1011
allOf:
11-
- $ref: './rt.yml#/components/schemas/ResultItem'
1212
- type: object
1313
properties:
1414
DocGraphicsInfo:
1515
$ref: "#/components/schemas/GraphicFieldsList"
16+
- $ref: './rt.yml#/components/schemas/ResultItem'
17+
1618

1719
GraphicFieldsList:
1820
type: object

‎rt-images.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,16 @@ components:
33
schemas:
44

55
ImagesResult:
6+
title: "Images"
67
allOf:
7-
- $ref: './rt.yml#/components/schemas/ResultItem'
88
- type: object
99
required:
1010
- Images
1111
properties:
1212
Images:
1313
$ref: '#/components/schemas/Images'
14+
- $ref: './rt.yml#/components/schemas/ResultItem'
15+
1416

1517
Images:
1618
type: object

‎rt-ocr-lexical-analisis.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,17 +5,19 @@ components:
55

66
LexicalAnalysisResult:
77
deprecated: true
8+
title: "Lexical Analysis (deprecated)"
89
description: |
910
Lexical data analysis allows you to compare the results of reading the text data of the MRZ,
1011
the document filling area, barcodes and data from the memory of the RFID chip for an additional
1112
assessment of the authenticity of the document. Single result for all pages.
1213
Deprecated since 5.2. Instead consider to use Result.TEXT type.
1314
allOf:
14-
- $ref: './rt.yml#/components/schemas/ResultItem'
1515
- type: object
1616
properties:
1717
ListVerifiedFields:
1818
$ref: '#/components/schemas/ListVerifiedFields'
19+
- $ref: './rt.yml#/components/schemas/ResultItem'
20+
1921

2022
ListVerifiedFields:
2123
type: object

‎rt-raw-image.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@ components:
33
schemas:
44

55
DocumentImageResult:
6+
title: "Document Image"
67
allOf:
7-
- $ref: './rt.yml#/components/schemas/ResultItem'
88
- type: object
99
description: "Contains cropped and rotated with perspective compensation image of document.
1010
Single input image can contain multiple document side/pages, which will be returned as separated results.
@@ -14,3 +14,4 @@ components:
1414
properties:
1515
RawImageContainer:
1616
$ref: "./common.yml#/components/schemas/ImageData"
17+
- $ref: './rt.yml#/components/schemas/ResultItem'

0 commit comments

Comments
 (0)