Gunakan Spring Boot dan Swagger untuk membina dokumentasi API RESTful

Dalam pembangunan web hari ini, RESTful API telah menjadi cara yang sangat popular untuk pembangun membina tapak web dan aplikasi. Menggunakan API RESTful, pembangun boleh membina API yang jelas untuk berinteraksi dengan aplikasi atau perkhidmatan lain dengan lebih mudah. Untuk mengurus dan menyelenggara API ini dengan lebih baik, penulisan dan pengurusan dokumen juga telah menjadi bahagian yang sangat kritikal.

Spring Boot ialah rangka kerja untuk membina aplikasi Java dengan cepat, yang ringkas, pantas dan mudah dikembangkan. Swagger ialah alat yang digunakan khusus untuk mereka bentuk, membina dan mendokumenkan API RESTful. Ia boleh menjana dokumen API RESTful dengan cepat dan menjana aliran sampel permintaan dan respons API.

Artikel ini akan memperkenalkan cara menggunakan Spring Boot dan Swagger untuk membina dokumen API RESTful.

1. Buat projek Spring Boot

Mula-mula, kita perlu menggunakan Spring Initializr untuk mencipta projek Spring Boot, yang boleh dibuat melalui https://start.spring.io/. Di sini, kami memilih dua kebergantungan Web dan Swagger 2. Selepas penciptaan selesai, kami mengimport projek ke dalam persekitaran pembangunan bersepadu dan menambah kebergantungan Swagger dalam pom.xml:

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

2. Cipta API RESTful

Di sini kami cipta RESTful mudah API untuk menjana nombor rawak.

Kami menambah kaedah dalam Pengawal:

@RestController
public class NumberController {
 
   @ApiOperation(value = "Generate a random number between 1 and 100")
   @RequestMapping(value = "/generateNumber", method = RequestMethod.GET)
   public ResponseEntity<Integer> generateNumber() {
       Random random = new Random();
       int randomNumber = random.nextInt(100) + 1;
       return ResponseEntity.ok(randomNumber);
   }
}

Perlu diambil perhatian bahawa bukan sahaja anotasi @RestController perlu ditambahkan pada kelas, tetapi anotasi @Api juga perlu digunakan untuk menerangkan peranan Pengawal ini.

Kandungan yang dinyahkompilasi:

package com.example.demo.controller;

import io.swagger.annotations.ApiOperation;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import java.util.Random;

@RestController
public class NumberController
{

    public NumberController()
    {
    }

    @ApiOperation(value="Generate a random number between 1 and 100")
    @RequestMapping(value="/generateNumber", method=RequestMethod.GET)
    public ResponseEntity generateNumber()
    {
        Random random = new Random();
        int randomNumber = random.nextInt(100) + 1;
        return ResponseEntity.ok(new Integer(randomNumber));
    }
}

3. Konfigurasikan Swagger

Selepas melengkapkan pembangunan Pengawal yang sepadan, kita perlu mengkonfigurasi Swagger. Tambahkan konfigurasi berkaitan Swagger pada aplikasi fail konfigurasi Spring Boot.properties.

#指定Swagger API扫描的路径
swagger.basePackage=com.example.demo.controller
 
#应用名称
swagger.title=Spring Boot Swagger Example
 
#版本号
swagger.version=1.0.0
 
#描述信息
swagger.description=This is a demo service for Spring Boot Swagger.
 
#联系人信息
swagger.contact.name=John Doe
swagger.contact.url=http://www.example.com
swagger.contact.email=john.doe@example.com

Penerangan anotasi:

@Api: Digunakan untuk menerangkan peranan Pengawal, serupa dengan anotasi @Controller dan @RequestMapping dalam Spring MVC.

@ApiIgnore: digunakan untuk API yang diabaikan dan tidak akan dipaparkan dalam dokumentasi API yang dijana.

@ApiOperation: digunakan untuk menerangkan operasi API tertentu, termasuk nama kaedah, kaedah permintaan, parameter permintaan, objek pemulangan dan maklumat lain, yang boleh diletakkan pada kaedah atau kelas.

@ApiImplicitParam: digunakan untuk menerangkan parameter permintaan, termasuk nama parameter, jenis parameter, keperluan dan maklumat lain.

@ApiModel: digunakan untuk menerangkan kelas JavaBean.

@ApiParam: digunakan untuk menerangkan maklumat parameter.

@ApiResponses: Digunakan untuk menerangkan respons API, termasuk kod status HTTP, data respons dan maklumat lain.

@ApiProperty: digunakan untuk menerangkan maklumat sifat kelas JavaBean.

4. Lihat dokumentasi API

Selepas melengkapkan konfigurasi di atas, kami memulakan aplikasi Spring Boot dan melawati http://localhost:8080/swagger-ui.html. Kami boleh melihat dokumentasi API yang dijana dalam penyemak imbas. Di sini kami boleh melihat maklumat terperinci API yang baru kami tulis, termasuk kaedah permintaan, parameter permintaan, hasil pemulangan, dsb. Pada masa yang sama, Swagger juga boleh menjana aliran sampel permintaan dan respons untuk memudahkan pembangun membuat rujukan dan ujian.

Di sini, kami menggunakan Spring Boot dan Swagger untuk membina dokumentasi API RESTful. Menggunakan kaedah ini, pembangun boleh membina dan mengurus dokumen API mereka sendiri dengan lebih cepat, meningkatkan kecekapan pembangunan dan kebolehselenggaraan.

Atas ialah kandungan terperinci Gunakan Spring Boot dan Swagger untuk membina dokumentasi API RESTful. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!