Cara menggunakan alat pengurusan antara muka bersepadu SpringBoot Swagger

1. Pengenalan kepada Swagger

Swagger ialah satu siri alatan API RESTful, anda boleh mendapatkan dokumen interaktif projek, penjanaan automatik SDK pelanggan dan fungsi lain.

Matlamat Swagger adalah untuk mentakrifkan antara muka bebas bahasa yang standard untuk REST API, supaya orang ramai dan komputer tidak dapat melihat kod sumber atau dokumen atau tidak boleh melepasi Keupayaan untuk menemui trafik rangkaian dan memahami fungsi pelbagai perkhidmatan. Apabila perkhidmatan ditakrifkan melalui Swagger, pengguna boleh berinteraksi dengan perkhidmatan jauh dengan sedikit logik pelaksanaan.

2. Springboot mengintegrasikan swagger

Konsep menggunakan Spring Boot untuk menyepadukan Swagger adalah menggunakan anotasi untuk menandakan maklumat yang perlu dipaparkan dalam dokumen API akan menggunakan anotasi yang ditanda dalam projek untuk Menjana dokumentasi API yang sepadan. Swagger dikenali sebagai alat API yang paling popular di dunia Ia menyediakan penyelesaian lengkap untuk pengurusan API.

1. Tambahkan koordinat swagger

Spring Boot menyepadukan Swagger 3 adalah sangat mudah. ​​Anda hanya perlu memperkenalkan kebergantungan dan melakukan konfigurasi asas.

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2. Pelaksanaan Swagger Helloword

2.1 Cipta projek springboot

Tambahkan anotasi @EnableOpenApi ke kelas permulaan untuk mendayakan fungsi dokumen api swagger

rreee.

2.2. Tulis antara muka

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.oas.annotations.EnableOpenApi;

@SpringBootApplication
@EnableOpenApi  //启动swagger api文档注解
public class SpringBootWithSwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SpringBootWithSwaggerApplication.class, args);
    }

}

2.3.3.3.

Swagger menunjukkan melalui anotasi bahawa antara muka akan menjana dokumen, termasuk nama antara muka, kaedah permintaan, parameter, maklumat pemulangan, dll.

1,

Api

anotasi dan

ApiOperation

anotasi

@Api

• digunakan pada kelas untuk menunjukkan bahawa ia adalah kesombongan sumber @API mempunyai dua atribut: value , tags.

  Dokumen api yang dijana akan dikelaskan mengikut teg Secara terang-terangan, dokumen antara muka yang dijana oleh semua antara muka dalam pengawal ini akan berada di bawah senarai teg jika teg mempunyai berbilang nilai, berbilang senarai akan dijana . Setiap senarai memaparkan semua antara muka

fungsi nilai seperti teg, tetapi tidak boleh mempunyai berbilang nilai

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author 阿水
 * @create 2023-04-11 9:54
 */
@RestController()
public class SwaggerController {
    @GetMapping ("hello")
    public String hello(String params) {
        return "hello swagger"+" param为:"+params;
    }
}

@ApiOperation

• digunakan untuk mewakili pengendalian permintaan http pada kaedah

  http://localhost:8080/swagger-ui/index.html

  Kes: Gunakan @Api dan @ApiOperation untuk menjana dokumen api

语法:
  @Api(tags = "用户操作")
  或
  @Api(tags = {"用户操作","用户操作2"})

2,

ApiImplicitParams

anotasi dan

ApiImplicitParam

@ApiImplicitParams anotasi dan @ApiImplicitParam

digunakan untuk parameter bukan objek dalam kaedah (pengikat parameter) apabila menggunakan jenis mudah. ​​) untuk penjelasan

语法:
    @ApiOperation(value = "", 
                  notes = "", 
                  response = )
属性说明：
  value：方法说明标题
  notes：方法详细描述
  response：方法返回值类型

Nota: Atribut nama @ApiImplicitParam harus menggemakan nilai @RequestParam atau @PathVariable. Kes: Gunakan anotasi @ApiImplicitParams dan @ApiImplicitParam untuk menerangkan parameter kaedah

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author 阿水
 * @create 2023-04-11 9:54
 */
@RestController()
@Api(tags = {"操作用户"})
public class SwaggerController {
    @GetMapping ("hello")
    @ApiOperation(value = "swagger请求",notes = "阿水的第一个swagger请求",response = String.class)
    public String hello(String params) {
        return "hello swagger"+" param为:"+params;
    }
}

3. Anotasi ApiModel dan ApiModelProperty

>>

@ApiModel

digunakan pada kelas entiti untuk menerangkan kelas dan digunakan untuk arahan penerimaan parameter dalam kelas entiti.

• 语法:
  @ApiImplicitParams(value = {
       @ApiImplicitParam(name="", value = "", type = "", required = true, paramType = "", defaultValue  = "")
  })
  
  属性说明：
      name:形参名称
      value:形参的说明文字
      type:形参类型
      required:该参数是否必须  true|false
      paramType: 用于描述参数是以何种方式传递到 Controller 的，它的值常见有： path, query, body 和 header 
          path 表示参数是『嵌在』路径中的，它和 @PathVariable 参数注解遥相呼应；
      	query 表示参数是以 query string 的形式传递到后台的（无论是 get 请求携带在 url 中，还是 post 请求携带在请求体中），它和 @RequestParam 参数注解遥相呼应；
      	header 表示参数是『藏在』请求头中传递到后台的，它和 @RequestHeader 参数注解遥相呼应的。
      	form 不常用.
      defaultValue :参数默认值

  4 ApiResponse dan ApiResponses

Anotasi @ApiResponses dan anotasi @ApiResponse ditandakan pada kaedah Pengawal untuk menerangkan respons permintaan HTTP

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author 阿水
 * @create 2023-04-11 9:54
 */
@RestController()
@Api(tags = {"操作用户"})
public class SwaggerController {
    @GetMapping ("hello")
    @ApiOperation(value = "swagger请求",notes = "阿水的第一个swagger请求",response = String.class)
    @ApiImplicitParams(value ={
            @ApiImplicitParam(name="param1",
                    value = "参数名1",
                    type = "String",
                    required = true,
                    paramType = "query",
                    defaultValue  = "阿水所想的默认值1" ),
            @ApiImplicitParam(name="param2",
                    value = "参数名2",
                    type = "String",
                    required = true,
                    paramType = "query",
                    defaultValue  = "阿水所想的默认值2" )
    })
    public String hello(String param1,String param2) {
        return "hello swagger"+" param1为:"+param1+"param2为"+param2;
    }
}

<. 🎜 >5. Cipta kelas konfigurasi SwaggerConfig

Tambah dua kaedah dalam SwaggerConfig: (satu kaedah ialah membuat persediaan tambahan untuk kaedah lain)

kaedah api() menggunakan @Bean, Dimulakan pada permulaan, instance Docket (objek ringkasan Swagger API) dikembalikan Apa yang perlu diperhatikan di sini ialah .apis(RequestHandlerSelectors.basePackage("xxx.yyy.zzz")) menentukan laluan pakej yang perlu diimbas Pengawal di bawah laluan ini Kelas akan menjana dokumentasi API Swagger secara automatik.

@ApiModel("用户类")
@Data
public class Users {

    @ApiModelProperty(value = "编码：主键")
    private Integer id;

    @ApiModelProperty(value = "用户名")
    private String username;

    @ApiModelProperty(value = "密码")
    private String password;

}

Konfigurasi kaedah apiInfo() agak penting Maklumat asas yang dipaparkan pada halaman konfigurasi utama termasuk tajuk, penerangan, versi, syarat perkhidmatan, dll. Jika anda melihat kod sumber kelas ApiInfo. , anda juga akan menemui lebih banyak konfigurasi seperti sokongan lesen

4 Springsecurity menyepadukan kesombongan

4.1, mengkonfigurasi alamat yang dikeluarkan

/**
     * 添加用户
     *
     * @param user
     * @return
     */
    @PostMapping("/add")
    @ApiOperation(value = "添加用户",notes = "添加用户信息",response = ResponseResult.class)
    @ApiResponses({ @ApiResponse(code = 200, message = "添加成功", response = ResponseResult.class),
            	    @ApiResponse(code = 500, message = "添加失败", response = ResponseResult.class) })
    public ResponseResult<Void> addUser(@RequestBody User user) {
        //获得生成的加密盐
        user.setSalt(SaltUtils.getSalt());
        int n = userService.addUser(user);
        if (n > 0) {
            return new ResponseResult<Void>(200, "添加成功");
        }
        return new ResponseResult<Void>(500, "添加失败");
    }

4.2, menggantikan UI

.

Keseluruhan proses di atas telah selesai, tetapi yang dihasilkan Malah, ramai orang tidak menyukai halaman dokumen antara muka, dan merasakan ia tidak selaras dengan tabiat penggunaan orang Cina, jadi beberapa pakar telah menyediakan yang lain halaman ujian UI. Penggunaan halaman ini agak meluas.

Import kebergantungan berikut, mulakan semula projek dan akses alamat: http://localhost:8080/doc.html

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * Swagger配置类
 */
@Configuration  //项目启动时加载此类
public class SwaggerConfig {
    @Bean
    public Docket api(){
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                // 此处自行修改为自己的 Controller 包路径。
                .apis(RequestHandlerSelectors.basePackage("com.lps.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    public ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("阿水的项目接口文挡")
                .description("阿水的 Project Swagger2 UserService Interface")  //说明信息
                .termsOfServiceUrl("http://localhost:8080/swagger-ui/index.html") //文档生成的主页地址
                .version("1.0")  //文档版本
                .build();
    }
}

Atas ialah kandungan terperinci Cara menggunakan alat pengurusan antara muka bersepadu SpringBoot Swagger. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!