swagger
Springfox
Recherche…
Remplacer les messages de réponse par défaut
Springfox définit un ensemble de messages de réponse par défaut qui sont appliqués à tous les contrôleurs API par défaut. Cela inclut par exemple 201 - Created
et 204 - No Content
, ainsi que plusieurs réponses 40x
. Dans certains cas, les messages de réponse par défaut ne s'appliquent pas à votre API. Vous devez intégrer des possibilités pour faire face à cela:
- Vous pouvez activer le message de réponse par défaut et définir votre propre message à l'aide de l'annotation
@ApiResponses
. - Vous pouvez définir vos propres messages de réponse globalement
Tour des messages de réponse par défaut
docket.useDefaultResponseMessages(false);
Vous pouvez maintenant définir vos messages de réponse individuels au niveau de chaque contrôleur. Par exemple
@ApiResponses(value = {
@ApiResponse(code=400, message = "This is a bad request, please stick to the API description", response = RestApiExceptionModel.class),
@ApiResponse(code=401, message = "Your request cannot be authorized.", response = RestApiExceptionModel.class)
})
Définissez vos propres messages de réponse par défaut
ModelRef errorModel = new ModelRef("RestApiExceptionModel");
List<ResponseMessage> responseMessages = Arrays.asList(
new ResponseMessageBuilder().code(401).message("Unauthorized").responseModel(errorModel).build(),
new ResponseMessageBuilder().code(403).message("Forbidden").responseModel(errorModel).build(),
new ResponseMessageBuilder().code(404).message("NotFound").responseModel(errorModel).build());
docket.globalResponseMessage(RequestMethod.POST, responseMessages)
.globalResponseMessage(RequestMethod.PUT, responseMessages)
.globalResponseMessage(RequestMethod.GET, responseMessages)
.globalResponseMessage(RequestMethod.DELETE, responseMessages);
Configurer springfox à l'aide de swagger-ui dans spring-boot
- Obtenez Springfox dans votre application en utilisant Maven ou Gradle
- Créez un nouveau bean Docket dans votre application et configurez-le
- Documentez votre API en fonction de vos besoins
- Lancez votre application et voyez vos résultats obtenus
# 1 Obtenir Springfox avec Maven
Ajoutez les dépendances pour swagger2 et swagger-ui dans votre pom.xml
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.0</version>
</dependency>
# 2 Configurez votre application pour utiliser Swagger
Ajoutez l'annotation @EnableSwagger2
à votre classe principale annotée @SpringBootApplication
et créez un bean Docket swagger dans cette classe de configuration (ou toute autre classe).
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
Cette configuration générera une documentation API sur tous les contrôleurs de printemps de votre application. Si vous avez besoin de limiter la génération de la documentation de l'API à certains contrôleurs, vous pouvez choisir entre différents RequestHandlerSelectors. Par exemple, vous pouvez générer votre documentation API en fonction de la structure de votre package à l'aide de RequestHandlerSelectors.basePackage("your.package.structure")
ou de classes spécifiques basées sur RequestHandlerSelectors.withClassAnnotation(Api.class)
aide de RequestHandlerSelectors.withClassAnnotation(Api.class)
.
# 3 Documentez votre API
Utilisez les annotations décrites dans la documentation pour améliorer vos classes et méthodes de contrôleur avec des informations supplémentaires. Pour décrire les informations générales de votre API, comme le titre général, la description ou la version, utilisez ApiInfoBuilder () dans votre bean Docket.
Exemple pour la définition de métadonnées à l'aide d'ApiInfoBuilder:
// Within your configuration class
public static ApiInfo metadata(){
return new ApiInfoBuilder()
.title("Your Title")
.description("Your Description")
.version("1.x")
.build();
}
// Within your method that definies the Docket bean...
docket.apiInfo(metadata());