/
Swagger V2.1.10 Annotations

Swagger V2.1.10 Annotations

Owned by Michael Bodkin (Unlicensed)
Last updated: Dec 23, 2022

Acceptance Criteria:

  1. All endpoints have a description and summery approved by Product Management that displays in the swagger UI using @Operation

    1. @GET @Operation(summary = "Get users", description = "Get list of users") public Response getUsers() {..}
    2. @GET @Path("/{username}") @Operation(summary = "Get user by user name", responses = { @ApiResponse(description = "The user", content = @Content(mediaType = "application/json", schema = @Schema(implementation = User.class))), @ApiResponse(responseCode = "400", description = "User not found")}) public Response getUserByName( @Parameter(description = "The name that needs to be fetched. Use user1 for testing. ", required = true) @PathParam("username") String username) throws ApiException { User user = userData.findUserByName(username); if (null != user) { return Response.ok().entity(user).build(); } else { throw new NotFoundException(404, "User not found"); } }

  2. All Json Objects have a description that display in the swagger UI using @Schema

    1. @Schema(name="DifferentModel", description="Sample model for the documentation") class OriginalModelEntity {...}
    2. @Schema(description = "pet status in the store", allowableValues = {"available","pending","sold"}) public String getStatus() { return status; }

  3. All Json Fields have a description and example using @Schema

    1. @Schema(description = "Question Id", example = "1") private String questionId;

  4. All Json Array Fields use @ArraySchema

    1. @GET @Path("/{referralId}/") @ApiResponse( responseCode = "200", description = "Success", content = @Content( mediaType = MediaType.APPLICATION_JSON, array = @ArraySchema(schema = @Schema(implementation = ReferralEntity.class)) )) @Operation(summary = "Get a referral source by Id") public Object fetchReferralsById(@Context HttpServletRequest request, @Context HttpServletResponse response, @PathParam("referralId") @Parameter(description = "Referral Source Id", schema = @Schema(implementation = int.class)) String id) throws Exception { if (!StringUtils.isNumeric(id)) { return ERR_MSG + request.getRequestURI(); } String clinicId = Processor.getClinicId(request); return referralsService.fetchReferrals("" + id, null, clinicId, request); }
    2. @Operation( summary = "Get a list of users", description = "Get a list of users registered in the system", responses = {@ApiResponse( responseCode = "200", description = "The response for the user request", content = { @Content( mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = User.class)) ) }) } ) @GET @SecurityRequirement(name = "JWT") @Path("/user") public List<User> getUsers() { return null; } class User { public String foo; }

  5. All request parameters have description and example. @Parameter

    1. @GET @Path("/{referralId}/") @ApiResponse( responseCode = "200", description = "Success", content = @Content( mediaType = MediaType.APPLICATION_JSON, array = @ArraySchema(schema = @Schema(implementation = ReferralEntity.class)) )) @Operation(summary = "Get a referral source by Id") public Object fetchReferralsById(@Context HttpServletRequest request, @Context HttpServletResponse response, @PathParam("referralId") @Parameter(description = "Referral Source Id", schema = @Schema(implementation = int.class)) String id) throws Exception {

  6. All post entities use @Content

    1. @PUT @Consumes("application/json") @Operation(summary = "Update an existing pet", tags = {"pets"}, security = @SecurityRequirement( name = "petstore-auth", scopes = "write:pets"), responses = { @ApiResponse( content = @Content(mediaType = "application/json", schema = @Schema(implementation = Pet.class))), @ApiResponse(responseCode = "400", description = "Invalid ID supplied"), @ApiResponse(responseCode = "404", description = "Pet not found"), @ApiResponse(responseCode = "405", description = "Validation exception") } ) public Response updatePet( @RequestBody(description = "Pet object that needs to be added to the store", required = true, content = @Content( schema = @Schema(implementation = Pet.class))) Pet pet) { //.. }

  7. All wrong responses are hidden see @Hidden

    1. @POST @Path("{path: .*}") @Hidden public String wrongPath(@Context HttpServletRequest request) { return "wrong URI: " + request.getRequestURI(); }

Examples:

Example of Multiple Response Types with multiple errors: https://github.com/sunwavehealth/SunwaveEMR/blob/main/src/main/java/com/sunwave/rest/assessments/AssessmentsController.java

Array Schema for collections: https://github.com/sunwavehealth/SunwaveEMR/blob/79bb65f2cdb27dc317b8bd12de9ea0ead26f16fb/src/main/java/com/sunwave/rest/forms/status/FormStatusController.java

Class to control our version, security and the url list: https://github.com/sunwavehealth/SunwaveEMR/blob/79bb65f2cdb27dc317b8bd12de9ea0ead26f16fb/src/main/java/com/sunwave/rest/SunwaveApiDefinition.java We could make our lives easier by adding localhost:xxx to this list to use the swagger ui to test the rest endpoints.

Resources