Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
devel:documentation:architecture:dev:swagger [2018/06/13 05:11]
cirkval 		devel:documentation:architecture:dev:swagger [2023/10/19 10:46] (current)
chalupat [#3330] Replace Springfox with springdoc 2
Line 72: Line 72:
  public Docket exampleApi() {  public Docket exampleApi() {
  return api("eu.bcvsolutions.idm.example");  return api("eu.bcvsolutions.idm.example");
 + }
 +}
 +</code>
 +
 +springdoc version (13.1.0+)
 +<code java>
 +/**
 + * Example module swagger configuration
 + */
 +@Configuration
 +@ConditionalOnProperty(prefix = "springdoc.swagger-ui", name = "enabled", matchIfMissing = true)
 +public class ExampleSwaggerConfig extends AbstractSwaggerConfig {
 +
 + @Autowired private ExampleModuleDescriptor moduleDescriptor;
 +
 + @Override
 + protected ModuleDescriptor getModuleDescriptor() {
 + return moduleDescriptor;
 + }
 +
 + @Bean
 + public GroupedOpenApi exampleApi() {
 + return api("eu.bcvsolutions.idm.example.rest");
  }  }
 } }
Line 106: Line 129:
  ) {  ) {
  return new ResponseEntity<>(new Pong(message), HttpStatus.OK);   return new ResponseEntity<>(new Pong(message), HttpStatus.OK); 
 + }
 +}
 +</code>
 +
 +For springdoc version (13.1.0+) add [[https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations|new swagger annotations]] to controllers.
 +
 +<code java>
 +
 +/**
 + * Ping pong example controller
 + */
 +@RestController
 +@Enabled(ExampleModuleDescriptor.MODULE_ID)
 +@RequestMapping(value = BaseController.BASE_PATH + "/examples")
 +@Tag(name = ExampleController.TAG, description = "Example operations")
 +
 +public class ExampleController {
 +
 + protected static final String TAG = "Examples";
 + @Autowired private ExampleService service;
 +
 + @ResponseBody
 + @RequestMapping(method = RequestMethod.GET, path = "/ping")
 + @Operation(
 + summary = "Ping - Pong operation", 
 + description= "Returns message with additional informations",
 + operationId = "ping",
 +                tags={ ExampleController.TAG }
 +                responses = @ApiResponse(
 +                    responseCode = "200",
 +                    content = {
 +                            @Content(
 +                                    mediaType = BaseController.APPLICATION_HAL_JSON_VALUE,
 +                                    schema = @Schema(
 +                                            implementation = Pong.class
 +                                    )
 +                            )
 +                    }
 +            ))
 +    @SecurityRequirements({
 +        @SecurityRequirement(name = SwaggerConfig.AUTHENTICATION_BASIC),
 +        @SecurityRequirement(name = SwaggerConfig.AUTHENTICATION_CIDMST)
 +    })
 + public ResponseEntity<Pong> ping(
 + @Parameter(description = "In / out message", example = "hello")
 + @RequestParam(required = false, defaultValue = "hello") String message
 + ) {
 + return new ResponseEntity<>(service.ping(message), HttpStatus.OK); 
  }  }
 } }
Line 129: Line 200:
  @ApiModelProperty(required = true, notes = "Creation time")  @ApiModelProperty(required = true, notes = "Creation time")
  private DateTime created;  private DateTime created;
 +
 + // ... getters, setters
 +}
 +</code>
 +
 +For springdoc version (13.1.0+) add [[https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations|new swagger annotations]] to dtos.
 +
 +<code java>
 +/**
 + * Example ping - pong response dto
 + */
 +@Schema(description = "Ping - Pong response")
 +public class Pong implements BaseDto {
 +
 + private static final long serialVersionUID = 1L;
 + //
 + @Schema(requiredMode = Schema.RequiredMode.REQUIRED, description = "Unique pong identifier")
 + private UUID id;
 + @Schema(description = "Ping - Pong response message")
 + private String message;
 + @Schema(requiredMode = Schema.RequiredMode.REQUIRED, description = "Creation time")
 + private ZonedDateTime created;
  
  // ... getters, setters  // ... getters, setters
Line 299: Line 392:
   * Use ''produces = BaseController.APPLICATION\_HAL\_JSON\_VALUE'' in controller mapping   * Use ''produces = BaseController.APPLICATION\_HAL\_JSON\_VALUE'' in controller mapping
   * Use ''@ApiOperation(nickname = "<operatonId>")'' e.g. ''@ApiOperation(nickname = "ping")'' for controller methods - nickname (=> operationId) can be used in permalink.    * Use ''@ApiOperation(nickname = "<operatonId>")'' e.g. ''@ApiOperation(nickname = "ping")'' for controller methods - nickname (=> operationId) can be used in permalink. 
 +
 +in springdoc version (13.1.0+)
 +  * Add Swagger annotation. What can be written into annotation, will be written to annotation - will be shown in dynamic and static documentation. Static documentation extension is used, when annotation doesn't fit.
 +  * Use module-<module>.properties with ''PropertyModuleDescriptor''.
 +  * ''produces = BaseController.APPLICATION\_HAL\_JSON\_VALUE'' is set by default but you can override it
 +  * Use ''@Operation(operationId= "<operatonId>")'' e.g. ''@Operation(operationId= "ping")'' for controller methods can be used in permalink. 
  
 ===== Aggregator ===== ===== Aggregator =====
  • by cirkval