Skip to content
This repository was archived by the owner on Dec 25, 2024. It is now read-only.

Java, readme update #311

Merged
spacether merged 4 commits into from
Dec 2, 2023
Merged

Java, readme update #311

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
86de6e4
Readme update in template
spacether Dec 2, 2023
4503f5d
Readmes updated
spacether Dec 2, 2023
f240b4b
Readme updated
spacether Dec 2, 2023
58cc5d8
Redme updated, dict references changed to map
spacether Dec 2, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
130 changes: 57 additions & 73 deletions samples/client/3_0_3_unit_test/java/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,97 +9,113 @@ This Java package is automatically generated by the [OpenAPI JSON Schema Generat

## Requirements

Java 17
1. Java 17
2. Gradle

## Migration Guides
- [3.0.0 Migration Guide](migration_3_0_0.md)
- [2.0.0 Migration Guide](migration_2_0_0.md)
- [Migration from Other Python Generators](migration_other_python_generators.md)
- [Migration from Other Java Generators](migration_other_java_generators.md)


## Installation
### pip install

If the python package is hosted on a repository, you can install directly using:
To install the API client library to your local Maven repository, simply execute:

```sh
pip install git+https://github.com/GIT_USER_ID/GIT_REPO_ID.git
```shell
mvn clean install
```
(you may need to run `pip` with root permission: `sudo pip install git+https://github.com/GIT_USER_ID/GIT_REPO_ID.git`)

Then import the package:
```python
import org.openapijsonschematools.client
To deploy it to a remote Maven repository instead, configure the settings of the repository and execute:

```shell
mvn clean deploy
```

### Setuptools
Refer to the [OSSRH Guide](http://central.sonatype.org/pages/ossrh-guide.html) for more information.

### Maven users

Install via [Setuptools](http://pypi.python.org/pypi/setuptools).
Add this dependency to your project's POM:

```sh
python -m pip install . --user
```xml
<dependency>
<groupId>org.openapijsonschematools</groupId>
<artifactId>petstore</artifactId>
<version>0.0.1</version>
<scope>compile</scope>
</dependency>
```
(or `python -m pip install .` to install the package for all users)

Then import the package:
```python
import org.openapijsonschematools.client
### Others

At first generate the JAR by executing:

```shell
mvn clean package
```

Then manually install the following JARs:

- `target/petstore-0.0.1.jar`
- `target/lib/*.jar`


## Usage Notes
### Validation, Immutability, and Data Type
This python code validates data to schema classes and return back an immutable instance containing the data
which subclasses all validated schema classes. This ensure that
This Java code validates data to schema classes and return back an immutable instance containing the data. This ensure that
- valid data cannot be mutated and become invalid to a set of schemas
- the one exception is that files are not immutable, so schema instances storing/sending/receiving files are not immutable

Here is the mapping from json schema types to python subclassed types:
Here is the mapping from json schema types to Java types:

| Json Schema Type | Java Base Class |
| ---------------- | ----------------- |
| ---------------- | --------------- |
| object | FrozenMap (HashMap) |
| array | FrozenList (ArrayList) |
| string | String |
| number | Number, float, double, int, long |
| integer | int, long |
| number | Number (int, long, float, double) |
| integer | int, long, float, double (with values equal to integers) |
| boolean | boolean |
| null | Void (null) |
| AnyType (unset) | Object |

### Storage of Json Schema Definition in Python Classes
### Storage of Json Schema Definition in Java JsonSchema Classes
In openapi v3.0.3 there are ~ 28 json schema keywords. Almost all of them can apply if
type is unset. I have chosen to separate the storage of json schema definition info and output
validated classes for payload instantiation.
type is unset. I have chosen to separate the storage of
- json schema definition info
- output classes for validated Map (json schema type object) payloads
- output classes for validated List (json schema type array) payloads

<details>
<summary>Reason</summary>

This json schema data is stored in each class that is written for a schema, in a component or
other openapi document location. This class is only responsible for storing schema info.
Output classes like those that store dict payloads are written separately and are
returned by the Schema.validate method when that method is passed in dict input.
Output classes like those that store map payloads are written separately and are
returned by the JsonSchema.validate method when that method is passed in Map input.
This prevents payload property access methods from
colliding with json schema definition.
</details>

### Json Schema Type Object
Most component schemas (models) are probably of type object. Which is a map data structure.
Json schema allows string keys in this map, which means schema properties can have key names that are
invalid python variable names. Names like:
invalid Java variable names. Names like:
- "hi-there"
- "1variable"
- "@now"
- " "
- "from"

To allow these use cases to work, schemas.immutabledict is used as the base class of type object schemas.
This means that one can use normal dict methods on instances of these classes.
To allow these use cases to work, FrozenMap (which extends HashMap) is used as the base class of type object schemas.
This means that one can use normal Map methods on instances of these classes.

<details>
<summary>Other Details</summary>

- optional properties which were not set will not exist in the instance
- None is only allowed in as a value if type: "null" was included or nullable: true was set
- preserving the original key names is required to properly validate a payload to multiple json schemas
- getters are written for validly named required and optional properties
- null is only allowed in as a value if type: "null" was included or nullable: true was set
- because null is an allowed property value, it is not used to represent an unset property state
- if an optional property is requested and it does not exist in the Map, an UnsetPropertyException is thrown
</details>

### Json Schema Type + Format, Validated Data Storage
Expand Down Expand Up @@ -131,24 +147,12 @@ is stored as a string.

## Getting Started

Please follow the [installation procedure](#installation) and then run the following:
Please follow the [installation procedure](#installation) and then use the JsonSchema classes in
org.openapijsonschematools.client.components.schemas to validate input payloads and instances of validated Map and List
output classes. Json schemas allow multiple types for one schema, so a schema's validate method can have
allowed input and output types.


## Servers
| server_index | Class | Description |
| ------------ | ----- | ----------- |
| 0 | [Model0](docs/servers/0.md) | |

## Endpoints

All URIs are relative to the selected server
- The server is selected by passing in server_info and server_index into api_configuration.ApiConfiguration
- Code samples in endpoints documents show how to do this
- server_index can also be passed in to endpoint calls, see endpoint documentation

| HTTP request | Method | Description |
| ------------ | ------ | ----------- |

## Component Schemas

| Class | Description |
Expand Down Expand Up @@ -241,23 +245,3 @@ All URIs are relative to the selected server
| [UriReferenceFormat.UriReferenceFormat1](docs/components/schemas/UriReferenceFormat.md#urireferenceformat1) | |
| [UriTemplateFormat.UriTemplateFormat1](docs/components/schemas/UriTemplateFormat.md#uritemplateformat1) | |

## Notes for Large OpenAPI documents
If the OpenAPI document is large, imports in org.openapijsonschematools.client.apis.tags.tag_to_api and org.openapijsonschematools.client.components.schemass may fail with a
RecursionError indicating the maximum recursion limit has been exceeded. In that case, there are a couple of solutions:

Solution 1:
Use specific imports for apis and models like:
- tagged api: `from org.openapijsonschematools.client.apis.tags.default_api import DefaultApi`
- api for one path: `from org.openapijsonschematools.client.apis.paths.some_path import SomePath`
- api for one operation (path + verb): `from org.openapijsonschematools.client.paths.some_path.get import ApiForget`
- single model import: `from org.openapijsonschematools.client.components.schemas.pet import Pet`

Solution 2:
Before importing the package, adjust the maximum recursion limit as shown below:
```
import sys
sys.setrecursionlimit(1500)
import org.openapijsonschematools.client
from org.openapijsonschematools.client.apis.tags.tag_to_api import *
from org.openapijsonschematools.client.components.schemass import *
```
Loading