[JAVA] Ich habe versucht, mit Swagger mit Spring Boot zu beginnen

Sie sind verantwortlich für das Backend und das Frontend innerhalb des Teams. Ich werde für die Vorderseite verantwortlich sein.

Ich wollte, dass Sie zuerst nur die API vorbereiten. Als ich versuchte, Swagger zu verwenden, war das viel einfacher.

Nach der Untersuchung der Verwendung scheint es viele Möglichkeiten zu geben, dies zu tun. Ich beschloss, es aufzuschreiben, einschließlich des Arrangements. Dieses Mal werde ich Spring Boot verwenden, um das Designdokument mit einem Bottom-up-Ansatz zu transkribieren.

Bottom-up-Ansatz: Transkribieren aus dem Quellcode

Der Bottom-up-Ansatz besteht darin, einen Swagger basierend auf dem Quellcode zu erstellen. Die folgenden zwei Punkte beziehen sich auf den Bottom-up-Ansatz.

――Da das Entwurfsdokument basierend auf dem Quellcode fertiggestellt wird, wird es für das Dokument und den Code schwierig, voneinander abzuweichen. ――Vermeiden Sie das mühsame Schreiben des Quellcodes nach dem Erstellen des Designdokuments

Es gibt eine Geschichte wie "Ist es nicht ein Problem, wenn eine Überarbeitung stattfindet?" Da zuerst nur der Mund der API definiert wird, Ich denke, dass sich die Arbeitszeit nicht wesentlich von der Erstellung als Dokument unterscheidet.

Als ich diesmal nachgesehen habe, scheint es, dass die meisten Dinge mit Spring Boot und Swagger erledigt werden können Ich wollte es in Zukunft positiv nutzen.

Den diesmal erstellten Code finden Sie unter hier.

Spring Boot-Einstellungen

Einführung von Spring Fox

Bei Verwendung von Spring Fox wird das API-Designdokument aus dem Quellcode transkribiert.

Um Spring Fox zu installieren, können Sie die folgenden Abhängigkeiten lösen.

`build.gradle`


repositories {
  jcenter()
}

dependencies {
    compile "io.springfox:springfox-swagger2:2.9.2"
    compile 'io.springfox:springfox-swagger-ui:2.9.2'  //So verwenden Sie die Swagger-Benutzeroberfläche
}

Aktivieren Sie Spring Fox im Spring Boot

`SpringBootSwaggerApplication.java`


package com.example.springbootswagger;

//Importanweisung weggelassen

@SpringBootApplication
@EnableSwagger2
public class SpringBootSwaggerApplication {

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

    //Docket ist eine von Spring Fox bereitgestellte API. Erfordert Einstellungen zum Transkribieren mit Swagger
    @Bean
    public Docket petApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select() // ApiSelector :Wählen Sie die API aus, die mit Swagger transkribiert werden soll.
                    .paths(PathSelectors.ant("/pets/**")) //Swagger weckt nur alles auf, was dem angegebenen Pfad entspricht
                    .build() //Erstellen Sie ApiSelector
                .useDefaultResponseMessages(false) //Es weist automatisch einen undefinierten Statuscode zu. Deaktivieren Sie dieses Mal die automatische Gewährung
                .host("springbootswagger.example.com")
                .apiInfo(apiInfo()); //API-Informationen festlegen
    }

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

Wenn Sie sich den offiziellen Leitfaden ansehen, gibt es andere Einstellungen, die eine allgemeine Antwortnachricht zurückgeben. Sie können sicherheitsrelevante Einstellungen vornehmen. Dieses Mal wird das Volumen groß sein, also werde ich es weglassen.

Bei der Aufnahme in die Produktion müssen Anzeigebeschränkungen festgelegt werden. Wie machst du das? Lass es uns das nächste Mal ausprobieren.

Ich werde eine Anmerkung setzen

Nachdem die Einstellungen für Spring Boot und Spring Fox abgeschlossen wurden, lassen Sie Swagger sie tatsächlich transkribieren. Kommentieren Sie verschiedene Ressourcen.

Wenn Sie im einfachsten Zustand wie folgt schreiben, können Sie die Spezifikationen vorerst sehen.

`PetResource.java`


package com.example.springbootswagger;
//Importanweisung weggelassen

@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;
    }
}

Wenn Sie eine Anmerkung hinzufügen, die an jede Ressource der API angehängt werden soll, wird normalerweise Es transkribiert es einfach in Swagger. Es ist wunderbar.

So überprüfen Sie die Swagger-Benutzeroberfläche

Wenn Sie die Anwendung starten und auf "http: // localhost: 8080 / swagger-ui.html" zugreifen Der folgende Bildschirm wird angezeigt.

Übrigens, auch wenn Sie "swagger-ui.html" nicht definieren Wenn gradle die Abhängigkeit von io.springfox: springfox-swagger-ui: 2.9.2 auflöst Es scheint, dass es ohne Erlaubnis generiert wird.

Definieren Sie Swagger genauer

Wenn es sich um eine Anmerkung der von Spring bereitgestellten Controller-Ebene handelt, Dies wird sich in Swagger entsprechend widerspiegeln. Wenn Sie beispielsweise @PathVariable hinzufügen, wird dies wie folgt angezeigt.

Es gibt auch wesentliche Elemente. Wenn Sie anstelle von Spring eine von Swagger bereitgestellte Anmerkung hinzufügen, Ein benutzerfreundlicheres API-Designdokument wird erstellt.

Geben Sie einen Überblick über jede Ressource

`PetResource.java`


//Importanweisung weggelassen

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

    // @Ressourcenübersicht mit ApiOperation festlegen
    @ApiOperation(value = "This Resource fetch all reserved pets")
    @GetMapping(produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    public List<PetDto> pets() {
        return new ArrayList<>();
    }
}

Fügen Sie ein Antwortmuster hinzu

`PetResource.java`


//Importanweisung weggelassen

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

    @ApiOperation(value = "This Resource fetch a pet by id")
    //Mit ApiResponses können Sie mehrere Antworten definieren. Erforderliche Elemente für Code und Nachricht.
    @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();
    }
}

Nachwort

Dieses Mal habe ich die sicherheitsrelevanten Elemente aufgrund des Volumens weggelassen. Ich denke, ich werde es in einem anderen Artikel zusammenfassen. Danach ist es, wie ich in der Mitte schrieb, notwendig, etwas zu entwickeln, das in der Produktion nicht gezeigt werden kann. Ich bin gespannt, wie es geht.

Ich verwende SpringBoot. Soll ich also etwas mit Spring Security tun?

Verweise

** Klicken Sie hier für verschiedene Einstellungen bei der Installation. ** **. http://springfox.github.io/springfox/docs/current/#getting-started

** Klicken Sie hier für Swagger-Anmerkungen. ** **. https://github.com/swagger-api/swagger-core/wiki/annotations