Skip to content

Commit ac12f5c

Browse files
author
Badr NASS LAHSEN
authored
Merge pull request #4 from kfirfer/feature/kfirfer-annotations
Adding more annotation examples
2 parents 1e2b2bb + 642a239 commit ac12f5c

File tree

12 files changed

+2091
-923
lines changed

12 files changed

+2091
-923
lines changed

‎springdoc-openapi-test-app2/src/main/java/org/springdoc/demo/app2/api/PetApi.java‎

Lines changed: 66 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@
77

88
import io.swagger.v3.oas.annotations.Operation;
99
import io.swagger.v3.oas.annotations.Parameter;
10+
import io.swagger.v3.oas.annotations.enums.Explode;
11+
import io.swagger.v3.oas.annotations.enums.ParameterIn;
12+
import io.swagger.v3.oas.annotations.enums.ParameterStyle;
1013
import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
1114
import io.swagger.v3.oas.annotations.media.ArraySchema;
1215
import io.swagger.v3.oas.annotations.media.Content;
@@ -20,14 +23,13 @@
2023
import org.springframework.http.ResponseEntity;
2124
import org.springframework.web.bind.annotation.*;
2225
import org.springframework.web.multipart.MultipartFile;
23-
2426
import javax.validation.Valid;
2527
import javax.validation.constraints.NotNull;
2628
import java.util.List;
2729

28-
@SecurityScheme(name = "petstore_auth", type = SecuritySchemeType.OAUTH2, flows = @OAuthFlows(implicit = @OAuthFlow(authorizationUrl = "http://petstore.swagger.io/oauth/dialog", scopes = {
29-
@OAuthScope(name = "write:pets", description = "modify pets in your account"),
30-
@OAuthScope(name = "read:pets", description = "read your pets") })))
30+
@SecurityScheme(name = "petstore_auth", type = SecuritySchemeType.OAUTH2, flows = @OAuthFlows(implicit = @OAuthFlow(authorizationUrl = "https://petstore3.swagger.io/oauth/authorize", scopes = {
31+
@OAuthScope(name = "write:pets", description = "modify pets in your account"),
32+
@OAuthScope(name = "read:pets", description = "read your pets")})))
3133
@Tag(name = "pet", description = "the pet API")
3234
public interface PetApi {
3335

@@ -36,23 +38,25 @@ default PetApiDelegate getDelegate() {
3638
};
3739
}
3840

39-
@Operation(summary = "Add a new pet to the store", description = "", security = {
40-
@SecurityRequirement(name = "petstore_auth", scopes = { "write:pets", "read:pets" }) }, tags = { "pet" })
41-
@ApiResponses(value = { @ApiResponse(responseCode = "405", description = "Invalid input") })
42-
@PostMapping(value = "/pet", consumes = { "application/json", "application/xml" })
41+
@Operation(summary = "Add a new pet to the store", description = "Add a new pet to the store", security = {
42+
@SecurityRequirement(name = "petstore_auth", scopes = {"write:pets", "read:pets"})}, tags = {"pet"})
43+
@ApiResponses(value = {
44+
@ApiResponse(responseCode = "200", description = "Successful operation", content = {@Content(mediaType = "application/xml", schema = @Schema(implementation = Pet.class)), @Content(mediaType = "application/json", schema = @Schema(implementation = Pet.class))}),
45+
@ApiResponse(responseCode = "405", description = "Invalid input")
46+
})
47+
@PostMapping(value = "/pet", consumes = {"application/json", "application/xml", "application/x-www-form-urlencoded"})
4348
default void addPet(
44-
@Parameter(description = "Pet object that needs to be added to the store", required = true) @Valid @RequestBody Pet pet) {
49+
@Parameter(description = "Create a new pet in the store", required = true) @Valid @RequestBody Pet pet) {
4550
// return getDelegate().addPet(pet);
4651
}
4752

48-
@Operation(summary = "Deletes a pet", description = "", security = {
49-
@SecurityRequirement(name = "petstore_auth", scopes = { "write:pets", "read:pets" }) }, tags = { "pet" })
50-
@ApiResponses(value = { @ApiResponse(responseCode = "400", description = "Invalid ID supplied"),
51-
@ApiResponse(responseCode = "404", description = "Pet not found") })
52-
@DeleteMapping(value = "/pet/{petId}")
53+
@Operation(summary = "Deletes a pet", description = "", security = {
54+
@SecurityRequirement(name = "petstore_auth", scopes = {"write:pets", "read:pets"})}, tags = {"pet"})
55+
@ApiResponses(value = {@ApiResponse(responseCode = "400", description = "Invalid pet value")})
56+
@DeleteMapping(value = "/pet/{petId}")
5357
default ResponseEntity<Void> deletePet(
54-
@Parameter(description = "Pet id to delete", required = true) @PathVariable("petId") Long petId,
55-
@Parameter(description = "") @RequestHeader(value = "api_key", required = false) String apiKey) {
58+
@Parameter(description = "Pet id to delete", required = true) @PathVariable("petId") Long petId,
59+
@Parameter(description = "") @RequestHeader(value = "api_key", required = false) String apiKey) {
5660
return getDelegate().deletePet(petId, apiKey);
5761
}
5862

@@ -62,66 +66,72 @@ default ResponseEntity<Void> deletePet(
6266
@ApiResponse(responseCode = "200", description = "successful operation", content = @Content(array = @ArraySchema(schema = @Schema(implementation = Pet.class)))),
6367
@ApiResponse(responseCode = "400", description = "Invalid status value") })
6468
@GetMapping(value = "/pet/findByStatus", produces = { "application/xml", "application/json" })
65-
default ResponseEntity<List<Pet>> findPetsByStatus(
66-
@NotNull @Parameter(description = "Status values that need to be considered for filter", required = true) @Valid @RequestParam(value = "status", required = true) List<String> status) {
69+
default ResponseEntity<List<Pet>> findPetsByStatus(@Parameter(explode = Explode.TRUE, name = "status", in = ParameterIn.QUERY, description = "Status values that need to be considered for filter", style = ParameterStyle.FORM, schema = @Schema(type = "string", defaultValue = "available", allowableValues = {"available", "pending", "sold"})) @Valid @RequestParam(value = "status", required = false) List<String> status) {
6770
return getDelegate().findPetsByStatus(status);
6871
}
6972

70-
@Operation(summary = "Finds Pets by tags", description = "Muliple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.", security = {
71-
@SecurityRequirement(name = "petstore_auth", scopes = { "write:pets", "read:pets" }) }, tags = { "pet" })
72-
@ApiResponses(value = {
73-
@ApiResponse(responseCode = "200", description = "successful operation", content = @Content(array = @ArraySchema(schema = @Schema(implementation = Pet.class)))),
74-
@ApiResponse(responseCode = "400", description = "Invalid tag value") })
75-
@GetMapping(value = "/pet/findByTags", produces = { "application/xml", "application/json" })
73+
@Operation(summary = "Finds Pets by tags", description = "Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.", security = {
74+
@SecurityRequirement(name = "petstore_auth", scopes = {"write:pets", "read:pets"})}, tags = {"pet"})
75+
@ApiResponses(value = {
76+
@ApiResponse(responseCode = "200", description = "successful operation", content = @Content(array = @ArraySchema(schema = @Schema(implementation = Pet.class)))),
77+
@ApiResponse(responseCode = "400", description = "Invalid tag value", content = @Content)})
78+
@GetMapping(value = "/pet/findByTags", produces = {"application/xml", "application/json"})
7679
default ResponseEntity<List<Pet>> findPetsByTags(
77-
@NotNull @Parameter(description = "Tags to filter by", required = true) @Valid @RequestParam(value = "tags", required = true) List<String> tags) {
80+
@Parameter(description = "Tags to filter by", explode = Explode.TRUE, in = ParameterIn.QUERY, name = "tags", style = ParameterStyle.FORM) @Valid @RequestParam(value = "tags", required = false) List<String> tags) {
7881
return getDelegate().findPetsByTags(tags);
7982
}
8083

81-
@Operation(summary = "Find pet by ID", description = "Returns a single pet", security = {
82-
@SecurityRequirement(name = "api_key") }, tags = { "pet" })
83-
@ApiResponses(value = {
84-
@ApiResponse(responseCode = "200", description = "successful operation", content = @Content(schema = @Schema(implementation = Pet.class))),
85-
@ApiResponse(responseCode = "400", description = "Invalid ID supplied"),
86-
@ApiResponse(responseCode = "404", description = "Pet not found") })
87-
@GetMapping(value = "/pet/{petId}", produces = { "application/xml", "application/json" })
84+
@Operation(summary = "Find pet by ID", description = "Returns a single pet", security = {
85+
@SecurityRequirement(name = "api_key"),
86+
@SecurityRequirement(name = "petstore_auth", scopes = {"write:pets", "read:pets"})
87+
}, tags = {"pet"})
88+
@ApiResponses(value = {
89+
@ApiResponse(responseCode = "200", description = "successful operation", content = @Content(schema = @Schema(implementation = Pet.class))),
90+
@ApiResponse(responseCode = "400", description = "Invalid ID supplied", content = @Content),
91+
@ApiResponse(responseCode = "404", description = "Pet not found", content = @Content)})
92+
@GetMapping(value = "/pet/{petId}", produces = {"application/xml", "application/json"})
8893
default ResponseEntity<Pet> getPetById(
89-
@Parameter(description = "ID of pet to return", required = true) @PathVariable("petId") Long petId) {
94+
@Parameter(description = "ID of pet to return", required = true) @PathVariable("petId") Long petId) {
9095
return getDelegate().getPetById(petId);
9196
}
9297

93-
@Operation(summary = "Update an existing pet", description = "", security = {
94-
@SecurityRequirement(name = "petstore_auth", scopes = { "write:pets", "read:pets" }) }, tags = { "pet" })
95-
@ApiResponses(value = { @ApiResponse(responseCode = "400", description = "Invalid ID supplied"),
96-
@ApiResponse(responseCode = "404", description = "Pet not found"),
97-
@ApiResponse(responseCode = "405", description = "Validation exception") })
98-
@PutMapping(value = "/pet", consumes = { "application/json", "application/xml" })
98+
@Operation(summary = "Update an existing pet", description = "Update an existing pet by Id", operationId = "updatePet", security = {
99+
@SecurityRequirement(name = "petstore_auth", scopes = {"write:pets", "read:pets"})}, tags = {"pet"})
100+
@ApiResponses(value = {
101+
@ApiResponse(responseCode = "200", description = "Successful operation",
102+
content =
103+
{@Content(mediaType = "application/xml", schema = @Schema(implementation = Pet.class)), @Content(mediaType = "application/json", schema = @Schema(implementation = Pet.class))}
104+
),
105+
@ApiResponse(responseCode = "400", description = "Invalid ID supplied"),
106+
@ApiResponse(responseCode = "404", description = "Pet not found"),
107+
@ApiResponse(responseCode = "405", description = "Validation exception")})
108+
@PutMapping(value = "/pet", consumes = {"application/json", "application/xml", "application/x-www-form-urlencoded"})
99109
default ResponseEntity<Void> updatePet(
100-
@Parameter(description = "Pet object that needs to be added to the store", required = true) @Valid @RequestBody Pet pet) {
110+
@Parameter(description = "Update an existent pet in the store", required = true) @Valid @RequestBody Pet pet) {
101111
return getDelegate().updatePet(pet);
102112
}
103113

104-
@Operation(summary = "Updates a pet in the store with form data", description = "", security = {
105-
@SecurityRequirement(name = "petstore_auth", scopes = { "write:pets", "read:pets" }) }, tags = { "pet" })
106-
@ApiResponses(value = { @ApiResponse(responseCode = "405", description = "Invalid input") })
107-
@PostMapping(value = "/pet/{petId}", consumes = { "application/x-www-form-urlencoded" })
114+
@Operation(summary = "Updates a pet in the store with form data", description = "", security = {
115+
@SecurityRequirement(name = "petstore_auth", scopes = {"write:pets", "read:pets"})}, tags = {"pet"})
116+
@ApiResponses(value = {@ApiResponse(responseCode = "405", description = "Invalid input")})
117+
@PostMapping(value = "/pet/{petId}", consumes = {"application/x-www-form-urlencoded"})
108118
default ResponseEntity<Void> updatePetWithForm(
109-
@Parameter(description = "ID of pet that needs to be updated", required = true) @PathVariable("petId") Long petId,
110-
@Parameter(description = "Updated name of the pet") @RequestParam(value = "name", required = false) String name,
111-
@Parameter(description = "Updated status of the pet") @RequestParam(value = "status", required = false) String status) {
119+
@Parameter(description = "ID of pet that needs to be updated", required = true) @PathVariable("petId") Long petId,
120+
@Parameter(description = "Name of pet that needs to be updated") @RequestParam(value = "name", required = false) String name,
121+
@Parameter(description = "Status of pet that needs to be updated") @RequestParam(value = "status", required = false) String status) {
112122
return getDelegate().updatePetWithForm(petId, name, status);
113123
}
114124

115-
@Operation(summary = "uploads an image", description = "", security = {
116-
@SecurityRequirement(name = "petstore_auth", scopes = { "write:pets", "read:pets" }) }, tags = { "pet" })
117-
@ApiResponses(value = {
118-
@ApiResponse(responseCode = "200", description = "successful operation", content = @Content(schema = @Schema(implementation = ModelApiResponse.class))) })
119-
@PostMapping(value = "/pet/{petId}/uploadImage", produces = { "application/json" }, consumes = {
120-
"multipart/form-data" })
125+
@Operation(summary = "uploads an image", security = {
126+
@SecurityRequirement(name = "petstore_auth", scopes = {"write:pets", "read:pets"})}, tags = {"pet"})
127+
@ApiResponses(value = {
128+
@ApiResponse(responseCode = "200", description = "successful operation", content = @Content(schema = @Schema(implementation = ModelApiResponse.class)))})
129+
@PostMapping(value = "/pet/{petId}/uploadImage", produces = {"application/json"}, consumes = {
130+
"application/octet-stream"})
121131
default ResponseEntity<ModelApiResponse> uploadFile(
122-
@Parameter(description = "ID of pet to update", required = true) @PathVariable("petId") Long petId,
123-
@Parameter(description = "Additional data to pass to server") @RequestParam(value = "additionalMetadata", required = false) String additionalMetadata,
124-
@Parameter(description = "file detail") @Valid @RequestPart("file") MultipartFile file) {
132+
@Parameter(description = "ID of pet to update", required = true) @PathVariable("petId") Long petId,
133+
@Parameter(description = "Additional Metadata") @RequestParam(value = "additionalMetadata", required = false) String additionalMetadata,
134+
@io.swagger.v3.oas.annotations.parameters.RequestBody(content = @Content(mediaType = "application/octet-stream", schema = @Schema(type = "string", format = "binary"))) @Valid @RequestPart("file") MultipartFile file) {
125135
return getDelegate().uploadFile(petId, additionalMetadata, file);
126136
}
127137

‎springdoc-openapi-test-app2/src/main/java/org/springdoc/demo/app2/api/StoreApi.java‎

Lines changed: 25 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -33,43 +33,44 @@ default StoreApiDelegate getDelegate() {
3333
};
3434
}
3535

36-
@Operation(summary = "Delete purchase order by ID", tags = { "store" })
37-
@ApiResponses(value = { @ApiResponse(responseCode = "400", description = "Invalid ID supplied"),
38-
@ApiResponse(responseCode = "404", description = "Order not found") })
39-
@DeleteMapping(value = "/store/order/{orderId}")
36+
@Operation(summary = "Delete purchase order by ID", description = "For valid response try integer IDs with value < 1000. Anything above 1000 or nonintegers will generate API errors", tags = {"store"})
37+
@ApiResponses(value = {@ApiResponse(responseCode = "400", description = "Invalid ID supplied"),
38+
@ApiResponse(responseCode = "404", description = "Order not found")})
39+
@DeleteMapping(value = "/store/order/{orderId}")
4040
default ResponseEntity<Void> deleteOrder(
41-
@Parameter(description = "ID of the order that needs to be deleted", required = true) @PathVariable("orderId") String orderId) {
41+
@Parameter(description = "ID of the order that needs to be deleted", required = true, schema = @Schema(type = "integer", format = "int64")) @PathVariable("orderId") Long orderId) {
4242
return getDelegate().deleteOrder(orderId);
4343
}
4444

45-
@Operation(summary = "Returns pet inventories by status", description = "Returns a map of status codes to quantities", security = {
46-
@SecurityRequirement(name = "api_key") }, tags = { "store" })
47-
@ApiResponses(value = {
48-
@ApiResponse(responseCode = "200", description = "successful operation", content = @Content(array = @ArraySchema(schema = @Schema(implementation = Map.class)))) })
49-
@GetMapping(value = "/store/inventory", produces = { "application/json" })
45+
@Operation(summary = "Returns pet inventories by status", description = "Returns a map of status codes to quantities", security = {
46+
@SecurityRequirement(name = "api_key")}, tags = {"store"})
47+
@ApiResponses(value = {
48+
@ApiResponse(responseCode = "200", description = "successful operation", content = @Content(schema = @Schema(type = "object")))})
49+
@GetMapping(value = "/store/inventory", produces = {"application/json"})
5050
default ResponseEntity<Map<String, Integer>> getInventory() {
5151
return getDelegate().getInventory();
5252
}
5353

54-
@Operation(summary = "Find purchase order by ID", tags = { "store" })
55-
@ApiResponses(value = {
56-
@ApiResponse(responseCode = "200", description = "successful operation", content = @Content(schema = @Schema(implementation = Order.class))),
57-
@ApiResponse(responseCode = "400", description = "Invalid ID supplied"),
58-
@ApiResponse(responseCode = "404", description = "Order not found") })
59-
@GetMapping(value = "/store/order/{orderId}", produces = { "application/xml", "application/json" })
54+
@Operation(summary = "Find purchase order by ID", description = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions", tags = {"store"})
55+
@ApiResponses(value = {
56+
@ApiResponse(responseCode = "200", description = "successful operation", content = @Content(schema = @Schema(implementation = Order.class))),
57+
@ApiResponse(responseCode = "400", description = "Invalid ID supplied", content = @Content),
58+
@ApiResponse(responseCode = "404", description = "Order not found", content = @Content)
59+
})
60+
@GetMapping(value = "/store/order/{orderId}", produces = {"application/xml", "application/json"})
6061
default ResponseEntity<Order> getOrderById(
61-
@Min(1L) @Max(5L) @Parameter(description = "ID of pet that needs to be fetched", required = true) @PathVariable("orderId") Long orderId) {
62+
@Min(1L) @Max(5L) @Parameter(description = "ID of order that needs to be fetched", required = true) @PathVariable("orderId") Long orderId) {
6263
return getDelegate().getOrderById(orderId);
6364
}
6465

65-
@Operation(summary = "Place an order for a pet", tags = { "store" })
66-
@ApiResponses(value = {
67-
@ApiResponse(responseCode = "200", description = "successful operation", content = @Content(schema = @Schema(implementation = Order.class))),
68-
@ApiResponse(responseCode = "400", description = "Invalid Order") })
69-
@PostMapping(value = "/store/order", produces = { "application/xml", "application/json" }, consumes = {
70-
"application/json" })
66+
@Operation(summary = "Place an order for a pet", description = "Place a new order in the store", tags = {"store"})
67+
@ApiResponses(value = {
68+
@ApiResponse(responseCode = "200", description = "successful operation", content = @Content(schema = @Schema(implementation = Order.class))),
69+
@ApiResponse(responseCode = "405", description = "Invalid input", content = @Content)
70+
})
71+
@PostMapping(value = "/store/order", produces = {"application/json"}, consumes = {"application/xml", "application/json", "application/x-www-form-urlencoded"})
7172
default ResponseEntity<Order> placeOrder(
72-
@Parameter(description = "order placed for purchasing the pet", required = true) @Valid @RequestBody Order order) {
73+
@io.swagger.v3.oas.annotations.parameters.RequestBody(description = "") @Valid @RequestBody Order order) {
7374
return getDelegate().placeOrder(order);
7475
}
7576

‎springdoc-openapi-test-app2/src/main/java/org/springdoc/demo/app2/api/StoreApiDelegate.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ default Optional<NativeWebRequest> getRequest() {
2424
/**
2525
* @see StoreApi#deleteOrder
2626
*/
27-
default ResponseEntity<Void> deleteOrder( String orderId) {
27+
default ResponseEntity<Void> deleteOrder( Long orderId) {
2828
return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
2929

3030
}

0 commit comments

Comments
 (0)