Bagaimana untuk menggunakan Swagger untuk menjana dokumentasi API?

Dengan perkembangan pesat aplikasi web, dokumentasi API menjadi semakin penting. Dokumentasi API direka bentuk untuk membantu pembangun memahami kaedah dan parameter penggunaan API, mengurangkan pembaziran masa dan sumber. Walau bagaimanapun, menulis dokumentasi API secara manual boleh menyusahkan dan memakan masa Pada masa ini, Swagger menjadi alat yang berkuasa untuk pembangun. Swagger ialah alat dokumentasi API yang popular yang boleh menjana dokumentasi API yang boleh dibaca dan interaktif secara automatik. Dalam artikel ini, kami memperkenalkan cara menggunakan Swagger untuk menjana dokumentasi API secara automatik.

Apakah Swagger?

Swagger ialah satu set alat sumber terbuka yang membantu pembangun membina, mereka bentuk, menerangkan dan menggunakan perkhidmatan web RESTful. Swagger membolehkan anda menulis dokumentasi API menggunakan format YAML atau JSON yang digunakan untuk menerangkan operasi API dan menjana dokumentasi antara muka yang mudah dibaca dan berinteraksi.

Swagger menyokong berbilang bahasa pengaturcaraan dan rangka kerja seperti Java, C#, Python dan Ruby. Ia juga boleh disepadukan dengan banyak rangka kerja API sedia ada, termasuk Spring, Express, Django, dll.

Menggunakan Swagger untuk menjana dokumentasi API memerlukan pemasangan Swagger UI terlebih dahulu. UI Swagger ialah tapak web dokumentasi API interaktif yang bebas daripada API dan mengikut spesifikasi Swagger. Ia menyediakan antara muka yang cantik untuk menggambarkan dokumentasi API dan menyokong percubaan automatik pada panggilan API.

Langkah 1: Konfigurasikan Swagger

Untuk menggunakan Swagger, anda perlu memuat turun pakej Swagger terlebih dahulu, yang boleh diperolehi daripada laman web Swagger atau dimuat turun menggunakan pengurus kebergantungan.

Untuk mengkonfigurasi API Swagger dalam projek Java Spring Boot, anda perlu menambah kebergantungan Swagger berikut dalam kebergantungan maven:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${springfox-swagger2.version}</version>
</dependency>
 
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${springfox-swagger-ui.version}</version>
</dependency>

di mana ${springfox-swagger2.version} dan ${ springfox-swagger-ui .version} mewakili nombor versi Swagger. Dayakan swagger dalam aplikasi fail konfigurasi.properties:

#开启swagger
swagger.enabled = true

Langkah 2: Tulis anotasi Swagger

Swagger menggunakan anotasi untuk menerangkan operasi dan parameter dalam API. Tambahkan anotasi Swagger di bahagian atas kelas pengawal API dan kaedahnya supaya Swagger boleh menghuraikan dan menjana dokumen dengan betul serta memaparkannya pada UI Swagger.

Berikut ialah beberapa contoh anotasi:

1. @Api: digunakan untuk menambah maklumat penerangan API

@Api(value="User",tags={"User 操作接口"})
@Controller
@RequestMapping("/users")
public class UserController {
    // ...
}

2. @ApiOperation: digunakan untuk menambah maklumat Perihalan operasi API

@ApiOperation(value = "获取用户列表", notes = "")
@GetMapping(value = "/list")
public Result getUserList() {
    List<User> userList = userService.listUser();
    return Result.success(userList);
}

3. @ApiParam: Maklumat penerangan yang digunakan untuk menambah parameter operasi API

@ApiOperation(value = "获取用户信息", notes = "根据url的id来获取用户详细信息")
@GetMapping(value = "/{id}")
public Result getUserById(@ApiParam(value = "用户ID", required = true) @PathVariable Long id) {
    User user = userService.getUserById(id);
    return Result.success(user);
}

Langkah 3: Lancarkan aplikasi dan akses Swagger UI

Selepas melengkapkan menulis anotasi Swagger, gunakan penyemak imbas untuk membuka alamat UI Swagger. Ia secara automatik membina dokumentasi API visual berdasarkan API anda.

Alamat lalai UI Swagger ialah: http://localhost:8080/swagger-ui.html

Pada antara muka UI Swagger, anda boleh melihat gambaran keseluruhan API dan pelbagai API Perihalan antara muka, parameter permintaan dan tindak balas, dan beberapa kod ujian, dsb. Ini boleh membantu pembangun lebih memahami dan menggunakan API.

Ringkasan

Swagger ialah alat dokumentasi API yang berkuasa yang boleh menjana dokumentasi API secara automatik yang mudah dibaca dan berinteraksi. Menggunakan Swagger boleh meningkatkan kecekapan dan kualiti pembangunan API serta mengurangkan masa dan sumber yang diperlukan untuk menulis dokumentasi API secara manual. Dengan mengikut langkah di atas, anda boleh mula menggunakan Swagger untuk menjana dokumentasi API secara automatik.

Atas ialah kandungan terperinci Bagaimana untuk menggunakan Swagger untuk menjana dokumentasi API?. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!