[JAVA] J'ai essayé de démarrer avec Swagger en utilisant Spring Boot

Vous serez en charge du back end et du front end au sein de l'équipe, Je serai en charge de la face avant.

Je voulais que vous prépariez d'abord uniquement l'API, donc quand j'ai essayé d'utiliser Swagger, c'était beaucoup plus facile.

Après avoir étudié comment l'utiliser, il semble qu'il existe de nombreuses façons de le faire. J'ai décidé de l'écrire, y compris l'arrangement. Cette fois, j'utiliserai Spring Boot pour transcrire le document de conception avec une approche ascendante.

Approche ascendante: transcription à partir du code source

L'approche ascendante consiste à créer un Swagger basé sur le code source. Les deux points suivants sont bons pour l'approche ascendante.

―― Puisque le document de conception est terminé sur la base du code source, il devient difficile pour le document et le code de s'écarter l'un de l'autre.

Éliminez les tracas liés à l'écriture du code source après la création du document de conception

Il y a une histoire comme "N'est-ce pas un problème si une retouche se produit?" Puisque seule l'embouchure de l'API est définie en premier, Je pense que le temps de travail n'est pas très différent du fait d'en faire un document.

Quand j'ai vérifié cette fois, il semble que la plupart des choses peuvent être faites avec Spring Boot et Swagger, donc Je voulais l'utiliser de manière positive à l'avenir.

Le code créé cette fois-ci se trouve à ici.

Paramètres de Spring Boot

Introduction de Spring Fox

En utilisant Spring Fox, le document de conception d'API est transcrit à partir du code source.

Pour installer Spring Fox, vous pouvez résoudre les dépendances suivantes.

`build.gradle`


repositories {
  jcenter()
}

dependencies {
    compile "io.springfox:springfox-swagger2:2.9.2"
    compile 'io.springfox:springfox-swagger-ui:2.9.2'  //Pour utiliser l'interface utilisateur Swagger
}

Activer Spring Fox dans Spring Boot

`SpringBootSwaggerApplication.java`


package com.example.springbootswagger;

//instruction d'importation omise

@SpringBootApplication
@EnableSwagger2
public class SpringBootSwaggerApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringBootSwaggerApplication.class, args);
    }

    //Docket est une API fournie par Spring Fox. Nécessite des paramètres pour transcrire avec Swagger
    @Bean
    public Docket petApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select() // ApiSelector :Sélectionnez l'API à transcrire avec Swagger.
                    .paths(PathSelectors.ant("/pets/**")) //Swagger ne réveillera que tout ce qui correspond au chemin spécifié
                    .build() //Créer ApiSelector
                .useDefaultResponseMessages(false) //Il attribue automatiquement un code de statut non défini. Cette fois, désactivez l'attribution automatique
                .host("springbootswagger.example.com")
                .apiInfo(apiInfo()); //Définir les informations de l'API
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Pet Service")
                .description("This is a pet service api")
                .version("1.0.0")
                .build();
    }
}

Si vous regardez le guide officiel, il existe d'autres paramètres qui renvoient un message de réponse commun, Vous pouvez définir des paramètres liés à la sécurité. Cette fois, le volume sera important, je vais donc l'omettre.

Lors de sa mise en production, il est nécessaire de définir des restrictions d'affichage. Comment faites-vous? Vérifions-le la prochaine fois.

Je mettrai une annotation

Maintenant que les paramètres de Spring Boot et Spring Fox sont terminés, laissez Swagger les transcrire. Annotez diverses ressources.

Si vous écrivez comme suit dans l'état le plus simple, vous pouvez voir les spécifications pour le moment.

`PetResource.java`


package com.example.springbootswagger;
//instruction d'importation omise

@RestController
@RequestMapping("/pets")
public class PetResource {

    @GetMapping
    public List<Map<String, String>> pets() {
        return new ArrayList<>();
    }

    @GetMapping("{id}")
    public Map<String, String> pet(@PathVariable String id) {
        return new HashMap<>();
    }

    @PutMapping("{id}")
    public void updatePet(@PathVariable String id) {
        return;
    }

    @PostMapping
    public int insertPet() {
        return 1;
    }

    @DeleteMapping
    public void deletePet() {
        return;
    }
}

Normalement, si vous ajoutez une annotation à attacher à chaque ressource de l'API, Il le transcrit simplement dans Swagger. C'est incroyable.

Comment vérifier l'interface utilisateur de Swagger

Lorsque vous démarrez l'application et accédez à http: // localhost: 8080 / swagger-ui.html L'écran suivant s'affiche.

Au fait, même si vous ne définissez pas swagger-ui.html Si gradle résout la dépendance de ʻio.springfox: springfox-swagger-ui: 2.9.2` Il semble qu'il sera généré sans autorisation.

Définissez Swagger plus en détail

S'il s'agit d'une annotation de la couche Controller fournie par Spring, Cela sera reflété dans Swagger en conséquence. Par exemple, si vous ajoutez @PathVariable, il sera reflété comme suit.

Il y a aussi des éléments essentiels. De plus, si vous ajoutez une annotation fournie par Swagger au lieu de Spring, Un document de conception d'API plus convivial sera créé.

Donner un aperçu de chaque ressource

`PetResource.java`


//instruction d'importation omise

@RestController
@RequestMapping("/pets")
public class PetResource {

    // @Définir la vue d'ensemble des ressources avec ApiOperation
    @ApiOperation(value = "This Resource fetch all reserved pets")
    @GetMapping(produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    public List<PetDto> pets() {
        return new ArrayList<>();
    }
}

Ajouter un modèle de réponse

`PetResource.java`


//instruction d'importation omise

@RestController
@RequestMapping("/pets")
public class PetResource {

    @ApiOperation(value = "This Resource fetch a pet by id")
    //Vous pouvez définir plusieurs réponses avec ApiResponses. Éléments requis pour le code et le message.
    @ApiResponses(value = {@ApiResponse(code = 400, message = "Invalid Id supplied", response = ErrorDto.class), @ApiResponse(code = 404, message = "Pet not found")})
    @GetMapping(value = "{id}", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    public PetDto pet(@PathVariable String id) {
        return new PetDto();
    }
}

Épilogue

Cette fois, j'ai omis les éléments liés à la sécurité en raison du volume. Je pense que je vais le résumer dans un autre article. Après cela, comme je l'ai écrit au milieu, il est nécessaire de concevoir quelque chose qui ne peut pas être montré en production. Je suis curieux de savoir comment le faire.

J'utilise SpringBoot, dois-je faire quelque chose avec Spring Security?

Les références

** Cliquez ici pour divers paramètres lors de l'installation. ** ** http://springfox.github.io/springfox/docs/current/#getting-started

** Cliquez ici pour les annotations Swagger. ** ** https://github.com/swagger-api/swagger-core/wiki/annotations