Skip to content

Commit cfa4169

Browse files
oharstaoharsta
committed
WIP for Swagger formatting
1 parent 80f0c78 commit cfa4169

File tree

2 files changed

+111
-19
lines changed

2 files changed

+111
-19
lines changed

‎server/src/main/java/invite/api/InvitationController.java‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,12 @@
1919
import invite.repository.UserRepository;
2020
import invite.security.SuperAdmin;
2121
import invite.security.UserPermissions;
22+
import io.swagger.v3.oas.annotations.Operation;
2223
import io.swagger.v3.oas.annotations.Parameter;
24+
import io.swagger.v3.oas.annotations.media.Content;
25+
import io.swagger.v3.oas.annotations.media.ExampleObject;
26+
import io.swagger.v3.oas.annotations.media.Schema;
27+
import io.swagger.v3.oas.annotations.responses.ApiResponse;
2328
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
2429
import jakarta.servlet.http.HttpServletRequest;
2530
import jakarta.servlet.http.HttpServletResponse;
@@ -103,6 +108,81 @@ public InvitationController(MailBox mailBox,
103108
}
104109

105110
@PostMapping("")
111+
@Operation(summary = "Invite member for existing Role",
112+
description = "Invite a member for an existing role. An invitation email will be sent. Do not forget to set guestRoleIncluded to true." +
113+
"At least one email must be either present in invites or invitations. When using the invitations you can also specify the " +
114+
"internalPlaceholderIdentifier, which will be used as the id in the SCIM POST to /User.",
115+
requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody(
116+
required = true,
117+
content = {@Content(
118+
mediaType = "application/json",
119+
examples = {
120+
@ExampleObject(
121+
name = "Invitation example",
122+
summary = "Example invitation request",
123+
value = """
124+
{
125+
"intendedAuthority": "INVITER",
126+
"message": "Personal message included in the email",
127+
"language": "en",
128+
"guestRoleIncluded": true,
129+
"invites": [
130+
"admin@service.org"
131+
],
132+
"invitations": [{
133+
"email": "admin2@service.org"
134+
"internalPlaceholderIdentifier": "4EFF937F-EE78-4A54-9FD8-A214FD64D7E1",
135+
}],
136+
"roleIdentifiers": [
137+
99
138+
],
139+
"roleExpiryDate": 1760788376,
140+
"expiryDate": 1730461976
141+
}
142+
"""
143+
)})}
144+
),
145+
responses = {
146+
@ApiResponse(responseCode = "201", description = "Created",
147+
content = {@Content(schema = @Schema(implementation = InvitationResponse.class),
148+
examples = {@ExampleObject(value = """
149+
{
150+
"status": 201,
151+
"recipientInvitationURLs": [
152+
{
153+
"recipient": "admin@service.nl",
154+
"invitationURL": "https://invite.test.surfconext.nl/invitation/accept?{hash}"
155+
}
156+
]
157+
}
158+
"""
159+
)})}),
160+
@ApiResponse(responseCode = "400", description = "BadRequest",
161+
content = {@Content(schema = @Schema(implementation = StatusResponse.class),
162+
examples = {@ExampleObject(value = """
163+
{
164+
"timestamp": 1717672263253,
165+
"status": 400,
166+
"error": "BadRequest",
167+
"exception": "access.exception.UserRestrictionException",
168+
"message": "No access to application",
169+
"path": "/api/internal/invite/invitations"
170+
}
171+
"""
172+
)})}),
173+
@ApiResponse(responseCode = "404", description = "Role not found",
174+
content = {@Content(schema = @Schema(implementation = StatusResponse.class),
175+
examples = {@ExampleObject(value = """
176+
{
177+
"timestamp": 1717672263253,
178+
"status": 404,
179+
"error": "Not found",
180+
"exception": "access.exception.NotFoundException",
181+
"message": "Role not found",
182+
"path": "/api/internal/invite/invitations"
183+
}
184+
"""
185+
)})})})
106186
public ResponseEntity<InvitationResponse> newInvitation(@Validated @RequestBody InvitationRequest invitationRequest,
107187
@Parameter(hidden = true) User user) {
108188
LOG.debug(String.format("New invitation request by user %s", user.getEduPersonPrincipalName()));

‎server/src/main/java/invite/internal/InternalInviteController.java‎

Lines changed: 31 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -288,26 +288,38 @@ public ResponseEntity<Void> deleteRole(@PathVariable("id") Long id,
288288
@PostMapping("/invitations")
289289
@PreAuthorize("hasAnyRole('SP_DASHBOARD','ACCESS')")
290290
@Operation(summary = "Invite member for existing Role",
291-
description = "Invite a member for an existing role. An invitation email will be sent. Do not forget to set guestRoleIncluded to true.",
291+
description = "Invite a member for an existing role. An invitation email will be sent. Do not forget to set guestRoleIncluded to true." +
292+
"At least one email must be either present in invites or invitations. When using the invitations you can also specify the " +
293+
"internalPlaceholderIdentifier, which will be used as the id in the SCIM POST to /User.",
292294
requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody(
293-
useParameterTypeSchema = true,
294-
content = {@Content(examples = {@ExampleObject(value = """
295-
{
296-
"intendedAuthority": "INVITER",
297-
"message": "Personal message included in the email",
298-
"language": "en",
299-
"guestRoleIncluded": true,
300-
"invites": [
301-
"admin@service.org"
302-
],
303-
"roleIdentifiers": [
304-
99
305-
],
306-
"roleExpiryDate": 1760788376,
307-
"expiryDate": 1730461976
308-
}
309-
"""
310-
)})}
295+
required = true,
296+
content = {@Content(
297+
mediaType = "application/json",
298+
examples = {
299+
@ExampleObject(
300+
name = "Invitation example",
301+
summary = "Example invitation request",
302+
value = """
303+
{
304+
"intendedAuthority": "INVITER",
305+
"message": "Personal message included in the email",
306+
"language": "en",
307+
"guestRoleIncluded": true,
308+
"invites": [
309+
"admin@service.org"
310+
],
311+
"invitations": [{
312+
"email": "admin2@service.org",
313+
"internalPlaceholderIdentifier": "4EFF937F-EE78-4A54-9FD8-A214FD64D7E1",
314+
}],
315+
"roleIdentifiers": [
316+
99
317+
],
318+
"roleExpiryDate": 1760788376,
319+
"expiryDate": 1730461976
320+
}
321+
"""
322+
)})}
311323
),
312324
responses = {
313325
@ApiResponse(responseCode = "201", description = "Created",

0 commit comments

Comments
 (0)