Pengenalan terperinci untuk menggunakan Swagger dalam pembangunan API Java

Swagger ialah alat yang sangat berguna dalam pembangunan API Java. Swagger ialah rangka kerja API sumber terbuka untuk menerangkan, mereka bentuk dan menjana perkhidmatan web RESTful. Ia menyediakan satu set anotasi untuk membantu pembangun menerangkan API dan parameter. Dalam artikel ini, saya akan menerangkan secara terperinci cara menggunakan Swagger dalam pembangunan API Java.

1. Pasang Swagger

Swagger boleh disepadukan ke dalam projek Java menggunakan Maven. Anda boleh menambah Swagger pada projek anda menggunakan kebergantungan Maven berikut:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

Selain itu, anda juga perlu menambah kebergantungan berikut, yang digunakan untuk menjana UI Swagger:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2. Mengkonfigurasi Swagger

Dalam aplikasi Java anda, anda perlu mengkonfigurasi Swagger. Untuk melakukan ini, anda boleh mencipta kelas konfigurasi untuk memulakan Swagger:

@Configuration
@EnableSwagger2
public class SwaggerConfig {    
    @Bean
    public Docket api() { 
        return new Docket(DocumentationType.SWAGGER_2)  
          .select()                                  
          .apis(RequestHandlerSelectors.any())              
          .paths(PathSelectors.any())                          
          .build();                                          
    }
}

Dalam kod di atas, kami telah menentukan kacang Docket, yang merupakan antara muka utama Swagger. Kami menggunakan ini untuk menentukan jenis API Swagger dan memetakannya dengan URL aplikasi.

3. Tambah anotasi Swagger

Kini anda boleh menambah anotasi Swagger dalam Java API. Berikut ialah beberapa anotasi Swagger yang biasa digunakan dan kegunaannya:

• @Api: digunakan untuk menerangkan keseluruhan API.
• @ApiOperation: digunakan untuk menerangkan operasi API.
• @ApiParam: digunakan untuk menerangkan parameter operasi.
• @ApiModel: Atribut model yang digunakan untuk menyediakan API.
• @ApiModelProperty: Sifat yang digunakan untuk menerangkan model API.

Anotasi ini boleh diletakkan pada kelas, kaedah, medan dan parameter kaedah serta boleh memberikan maklumat tentang ulasan API dengan menggunakan atribut nilai dan nota.

Sebagai contoh, jika anda mempunyai coretan kod berikut:

@RestController
@RequestMapping("/users")
public class UserController {
    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        // code to get user
    }
}

Anda boleh menggunakan anotasi Swagger untuk menerangkan kaedah getUser:

@RestController
@RequestMapping("/users")
@Api(value="用户管理", tags="用户管理")
public class UserController {
 
    @GetMapping("/{id}")
    @ApiOperation(value="获取用户信息", notes="根据用户ID获取用户信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
    public User getUser(@PathVariable Long id) {
        // code to get user
    }
}

Dalam kod di atas, kami telah menggunakan Anotasi @Api dan @ApiOperation. Anotasi @Api digunakan untuk menerangkan keseluruhan API, termasuk nama dan label. Anotasi @ApiOperation digunakan untuk menerangkan nama operasi, serta beberapa nota tentang operasi.

4. Jana Swagger UI

Kini setelah aplikasi Java anda dikonfigurasikan dengan anotasi Swagger dan Swagger, anda boleh menggunakan Swagger UI untuk memaparkan dan menguji API.

Untuk melakukan ini, anda boleh menambah baris berikut di bawah anotasi @Bean dalam kelas SwaggerConfig:

@Configuration
@EnableSwagger2
public class SwaggerConfig {    
    @Bean
    public Docket api() { 
        return new Docket(DocumentationType.SWAGGER_2)  
          .select()                                  
          .apis(RequestHandlerSelectors.any())              
          .paths(PathSelectors.any())                          
          .build();                                          
    }

    @Bean
    public UiConfiguration uiConfig() {
        return UiConfigurationBuilder.builder()
            .docExpansion(DocExpansion.LIST)
            .build();
    }
}

Ini akan menambah kacang uiConfig(), yang digunakan untuk mengkonfigurasi UI Swagger . Menggunakan kod di atas, kami menetapkan DocExpansion kepada LIST supaya semua tindakan dikembangkan secara lalai dalam UI.

5. Lancarkan aplikasi

Kini anda telah mengkonfigurasi anotasi Swagger dan Swagger dan menjana UI Swagger dalam kelas SwaggerConfig. Anda boleh melancarkan aplikasi menggunakan arahan berikut:

$ mvn spring-boot:run

Mengikut tetapan lalai Swagger, anda boleh mengakses UI Swagger daripada penyemak imbas. Navigasi ke http://localhost:8080/swagger-ui.html dan anda akan melihat bahawa UI Swagger sudah memaparkan API anda.

6. Menguji API

Akhir sekali, anda boleh menggunakan Swagger UI untuk menguji API. Dengan mengklik butang "Cuba", UI Swagger akan menghantar permintaan kepada API anda secara automatik dan anda akan melihat respons dalam UI.

Dalam artikel ini, saya memperkenalkan cara menggunakan Swagger dalam pembangunan API Java. Menggunakan Swagger, anda boleh menerangkan dan menguji API anda dengan mudah, dan anda boleh menjana dokumentasi yang mudah dibaca dan digunakan. Jika anda seorang pembangun Java, saya menggalakkan anda mencuba Swagger untuk memudahkan pembangunan dan ujian API.

Atas ialah kandungan terperinci Pengenalan terperinci untuk menggunakan Swagger dalam pembangunan API Java. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!