Skip to content

Commit 07b463d

Browse files
haunerhauner
committed
improved & extended docs
1 parent 78af462 commit 07b463d

5 files changed

Lines changed: 188 additions & 37 deletions

File tree

‎docs/generatr/index.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,9 @@ has_children: true
77

88
# The generatr
99

10-
The openapi-generatr-spring is an **interface only** open api generatr. That means it will only
11-
generate java interfaces for the endpoints. It is the projects task to implement them.
10+
The openapi-generatr-spring is an **interface only & model** open api generatr. That means it will
11+
only generate java interfaces for the endpoints and the required model POJO classes. It is the
12+
projects task to implement the endpoint interfaces.
1213

1314
Let's take a look at a very simple example. The following open api yaml describes a single
1415
endpoint. A call to the `/ping` endpoint will simply respond with a plain text string result.

‎docs/generatr/requestbody.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
---
2+
layout: default
3+
title: Request Body
4+
parent: The generatr
5+
nav_order: 15
6+
---
7+
8+
# Request Body
9+
10+
This OpenAPI describes an endpoint with `requestBody`:
11+
12+
```yaml
13+
openapi: 3.0.2
14+
info:
15+
title: request body
16+
version: 1.0.0
17+
18+
paths:
19+
/book:
20+
post:
21+
requestBody:
22+
content:
23+
application/json:
24+
schema:
25+
$ref: '#/components/schemas/Book'
26+
required: true
27+
responses:
28+
'201':
29+
description: created book
30+
content:
31+
application/json:
32+
schema:
33+
$ref: '#/components/schemas/Book'
34+
35+
components:
36+
schemas:
37+
Book:
38+
type: object
39+
properties:
40+
isbn:
41+
type: string
42+
title:
43+
type: string
44+
```
45+
46+
that the generatr will convert to the interface:
47+
48+
```java
49+
package generated.api;
50+
51+
import generated.model.Book;
52+
import org.springframework.http.ResponseEntity;
53+
import org.springframework.web.bind.annotation.PostMapping;
54+
import org.springframework.web.bind.annotation.RequestBody;
55+
56+
public interface Api {
57+
58+
@PostMapping(path = "/book", consumes = {"application/json"}, produces = {"application/json"})
59+
ResponseEntity<Book> postBook(@RequestBody Book body);
60+
61+
}
62+
```
63+
64+
and a `Book` pojo.
65+
66+
## multipart/form-data <span class="label label-green">since 1.0.0.M5</span>
67+
68+
For file uploads, where the `content` of the `requestBody` is `multipart/form-data`, the resulting
69+
code looks a bit different and requires a specific type mapping.
70+
71+
The file upload in OpenAPI is described like this:
72+
73+
```yaml
74+
/file-upload:
75+
summary: upload a file
76+
post:
77+
requestBody:
78+
content:
79+
multipart/form-data:
80+
schema:
81+
type: object
82+
properties:
83+
file:
84+
type: string
85+
format: binary
86+
```
87+
88+
(See also [OpenAPI - describing a file upload endpoint][howto-file-upload])
89+
90+
The `schema` must be of type `object` defining a property for each part in the multipart body.
91+
92+
Instead of generating a `@RequestBody` parameter for the `object` schema the generatr creates
93+
a parameter for each property of the object annotated with `@RequestParam`:
94+
95+
```java
96+
package generated.api;
97+
98+
import org.springframework.http.ResponseEntity;
99+
import org.springframework.web.bind.annotation.PostMapping;
100+
import org.springframework.web.bind.annotation.RequestParam;
101+
import org.springframework.web.multipart.MultipartFile;
102+
103+
public interface Api {
104+
105+
@PostMapping(path = "/file-upload")
106+
ResponseEntity<Void> postFileUpload(@RequestParam(name = "file") MultipartFile file);
107+
108+
}
109+
```
110+
111+
Note that the `file` property (type `string` format `binary`) is mapped to Springs `MultipartFile`
112+
type. The generatr does not have a default mapping for the `binary` format so to get the code
113+
above we have to configure it in the type mapping yaml:
114+
115+
```yaml
116+
map:
117+
paths:
118+
/file-upload:
119+
types:
120+
- from: string:binary
121+
to: org.springframework.web.multipart.MultipartFile
122+
```
123+
124+
To upload multiple files we can define the body `object` with an `array` property:
125+
126+
```yaml
127+
type: object
128+
properties:
129+
files:
130+
type: array
131+
items:
132+
type: string
133+
format: binary
134+
```
135+
136+
to get the following code:
137+
138+
```java
139+
@PostMapping(path = "/file-upload")
140+
ResponseEntity<Void> postFileUpload(@RequestParam(name = "files") MultipartFile[] files);
141+
```
142+
143+
144+
[howto-file-upload]: /openapi-generatr-spring/howto/file_upload.html
145+

‎docs/generatr/responses.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
layout: default
33
title: Responses
44
parent: The generatr
5-
nav_order: 10
5+
nav_order: 20
66
---
77

88
## Responses

‎docs/howto/global-array-mapping.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ parent: HowTo's
55
nav_order: 1
66
---
77

8-
# map openapi array (globally) to a java collection type
8+
# generatr: map openapi array (globally) to a java collection type
99

1010
By default the OpenAPI `array` is mapped to a simple java array. It is possible to change that default
1111
mapping for example to `java.util.Collection` by adding a type mapping to the [`mapping.yaml`][docs-mapping].

‎docs/index.md‎

Lines changed: 38 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,8 @@ correctly.
2828
See the [generatr intro][docs-generatr]{:target="_blank"} for a short example.
2929
{: .mb-6 }
3030

31-
Note that the generatr is still in an early state of development and not all features are completely implemented.
32-
(December 2019)
31+
January 2020: The generatr is ready to try but note that the generatr is still in an early state of
32+
development and may not generate the correct code yet in all cases. See [feedback](#feedback).
3333
{: .note .info .mb-6}
3434

3535

@@ -49,41 +49,19 @@ See the [release notes][generatr-releases]{:target="_blank"}.
4949

5050
## Features
5151

52-
- <span class="label label-green">partially implemented</span> generates only java interfaces and java model classes
53-
(get/set pojos) for all defined endpoints and schemas to allow (nearly) full control of the endpoint
54-
implementation. It does not generate any other file.
55-
56-
- <span class="label label-green">done (since 1.0.0.A2)</span> The generatr does now generate model classes
57-
with `@JsonProperty` annotated properties, i.e. the schema property names in the OpenAPI description are not limited
58-
to valid java identifiers anymore.
59-
60-
- <span class="label label-green">done (since 1.0.0.A2)</span> support for the OpenAPI `requestBody:` block.
61-
62-
- <span class="label label-green">done</span> full parameter support:
63-
- <span class="label label-green">done</span> query parameters, i.e. `in: query`
64-
- <span class="label label-green">done (since 1.0.0.A2)</span> path parameters, i.e. `in: path`
65-
- <span class="label label-green">done (since 1.0.0.A2)</span> header parameters, i.e. `in: header`
66-
- <span class="label label-green">done (since 1.0.0.A2)</span> cookie parameters, i.e. `in: cookie`
67-
{: .mb-5 }
68-
69-
- <span class="label label-green">partially implemented</span> simple & flexible type mappings with generic support
70-
(one level) to map schemas defined in the openapi.yaml to existing java types. For example to map the openapi
71-
`array` type to different java collections or to map paging parameters and results to Spring types like `Page<>`
72-
& `Pageable`.
52+
- generates only java interfaces and java model classes (get/set POJOs) for all defined endpoints and schemas to
53+
allow (nearly) full control of the endpoint implementation. It does not generate any other file. See
54+
[generatr][docs-generatr].
55+
56+
- powerful type mappings with generic support (one level) to map schemas defined in the openapi.yaml to
57+
existing java types. For example to map the openapi `array` type to different java collections or to
58+
map paging parameters and results to Spring types like `Page<>` & `Pageable`. See [type mapping][docs-mapping].
7359

7460
it is possible to define the mapping globally or for a specific response or parameter or even only for a specific
7561
endpoint.
76-
77-
- <span class="label label-red">caveat</span> the mapping can be defined at all levels but is not yet honored
78-
at all places.
79-
{: .mb-5 }
8062

81-
- <span class="label label-green">implemented</span> gradle support via [openapi-generatr-gradle][generatr-gradle] plugin.
82-
83-
- <span class="label label-red">caveat</span> the gradle plugin is currently the only option to run the
84-
generatr.
85-
{: .mb-5 }
86-
63+
- gradle support via [openapi-generatr-gradle][generatr-gradle] plugin (the plugin is currently the only option
64+
to run the generatr).
8765

8866
- <span class="label label-yellow">planned</span> add additional parameters to an endpoint which are not defined in
8967
the openapi description. For example to pass a `HttpServletRequest` to the endpoint implementation.
@@ -103,6 +81,30 @@ The generated source code has to be included in a project to compile it. This is
10381
with the [openapi-generatr-gradle][generatr-gradle] plugin. See [Using Gradle][docs-gradle].
10482
{: .note .info .mb-6}
10583

84+
## Feedback
85+
86+
In case some feature is missing or the generated code is not 100% what you would expect create an [issue][generatr-issues]
87+
preferably with a test case. Providing a test case will help significantly :-)
88+
89+
A test case is a single folder with an openapi.yaml file and the expected Java files the generatr should create.
90+
The structure looks like this:
91+
92+
my-new-test-case/
93+
openapi.yaml
94+
mapping.yaml
95+
generated/
96+
api/
97+
AnEndpointInterface.java
98+
.. more api interfaces ..
99+
model/
100+
AModelClass.java
101+
AnotherModelClass.java
102+
.. more model files ..
103+
104+
The `mapping.yaml` contains the type mapping information and is an optional file.
105+
106+
See the [existing integration tests][generatr-int-resources] for a couple of examples.
107+
106108
## License
107109

108110
openapi-generatr-spring is distributed by [Apache License 2.0][license].
@@ -124,11 +126,14 @@ openapi-generatr-spring is distributed by [Apache License 2.0][license].
124126

125127
[docs-gradle]: /openapi-generatr-spring/gradle.html
126128
[docs-generatr]: /openapi-generatr-spring/generatr/
129+
[docs-mapping]: /openapi-generatr-spring/mapping/
127130

128131
[bintray]: https://bintray.com/hauner/openapi-generatr
129132
[generatr-gradle]: https://github.com/hauner/openapi-generatr-gradle
130133
[generatr-releases]: https://github.com/hauner/openapi-generatr-spring/releases
131134
[generatr-license]: https://github.com/hauner/openapi-generatr-spring/blob/master/LICENSE
135+
[generatr-int-resources]: https://github.com/hauner/openapi-generatr-spring/tree/master/src/testInt/resources
136+
[generatr-issues]: https://github.com/hauner/openapi-generatr-spring/issues
132137

133138
[openapi]: https://www.openapis.org/
134139
[springboot]: https://spring.io/projects/spring-boot

0 commit comments

Comments
 (0)