第九节:SpringBoot在线文档Swagger2入门

Swagger2 是一个开源项目，用于为 RESTful Web 服务生成 REST API 文档。它提供了一个用户界面，可以通过 Web 浏览器访问我们的 RESTful Web 服务,测试接口。

SpringBoot集成Swagger2 3.0以下版本

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>

Swagger2Config配置文件

package com.rumenz.lession9.controller.config;

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @className: Swagger2Config
 * @description: TODO 类描述
 * @author: 入门小站 rumenz.com
 * @date: 2021/11/10
 **/

@Configuration
@EnableSwagger2 //Swagger2 3.0以下版本需要开启的注解
public class Swagger2Config {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.rumenz.lession9.controller"))
                .paths(PathSelectors.any()).build();
    }
    private ApiInfo apiInfo(){
        Contact contact=new Contact("入门小站", "https://rumenz.com", "[e-mail]");
        return new ApiInfoBuilder()
                .title("入门小站接口文档")
                .description("https://rumenz.com")
                .contact(contact).build();
    }
}

3.0以下开启@EnableSwagger2这个注解

浏览器访问http://127.0.0.1:8080/swagger-ui.html

SpringBoot集成Swagger2 3.0以版本

Swagger2 3.0版本使用更加简单

pom.xml

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

Swagger2Config配置问价相差不大。

package com.rumenz.lession9.controller.config;

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @className: Swagger2Config
 * @description: TODO 类描述
 * @author: 入门小站 rumenz.com
 * @date: 2021/11/10
 **/

@Configuration
public class Swagger2Config {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.rumenz.lession9.controller"))
                .paths(PathSelectors.any()).build();
    }
    private ApiInfo apiInfo(){
        Contact contact=new Contact("入门小站", "https://rumenz.com", "[e-mail]");
        return new ApiInfoBuilder()
                .title("入门小站接口文档")
                .description("https://rumenz.com")
                .contact(contact).build();
    }
}

3.0以上版本不需要@EnableSwagger2这个注解

启动类添加注解

package com.rumenz;

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

@SpringBootApplication
@EnableOpenApi //Swagger2 3.0以上版本需要开启的注解
public class Lession9Application {

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

}

注意添加@EnableOpenApi注解

浏览器访问http://127.0.0.1:8080/swagger-ui/

Swagger2常用注解

@Api

@Api用在类上,用于说明类功能的说明

@Api(tags = "入门小站Controller入口",value = "页面上看不见的内容")

@ApiOperation

@ApiOperation(value = "方法的作用说明",notes = "方法的备注说明")

@ApiImplicitParams,@ApiImplicitParam

入参数说明

@ApiImplicitParams({@ApiImplicitParam(name = "page",value = "当前页"),@ApiImplicitParam(name = "pageSize",value = "分页大小")})

@ApiImplicitParam其它参数

@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值

@ApiResponses

明请求返回的状态码及描述

@ApiResponses({@ApiResponse(code = 200,message = "成功"),@ApiResponse(code=201,message = "参数错误")})

@ApiModel

描述实体类

@ApiModel("用戶信息")

@ApiModelProperty

描述实体类的属性

@ApiModelProperty(value = "名字",name = "name",example = "入门小站")

演示案例

RumenzController

package com.rumenz.lession9.controller;

import io.swagger.annotations.*;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import org.springframework.web.bind.annotation.*;

/**
 * @className: RumenzController
 * @description: TODO 类描述
 * @author: 入门小站 rumenz.com
 * @date: 2021/11/10
 **/
@RestController
@RequestMapping("/rumenz")
//@Api用在类上,用于说明类功能的说明
@Api(tags = "入门小站Controller入口",value = "页面上看不见的内容")
public class RumenzController {

    @GetMapping("/index")
    public String index(){
        return "入门小站";
    }

    @GetMapping("/user")
    @ApiOperation(value = "方法的作用说明",notes = "方法的备注说明")
    //传入参数说明
    @ApiImplicitParams({@ApiImplicitParam(name = "page",value = "当前页"),@ApiImplicitParam(name = "pageSize",value = "分页大小")})
    //说明请求返回的状态码及描述
    @ApiResponses({@ApiResponse(code = 200,message = "成功"),@ApiResponse(code=201,message = "参数错误")})
    public String index1(@ApiParam("页数") @RequestParam("page") Integer page,@ApiParam("每页条数") Integer pageSize){
        return "入门小站";
    }

    @PostMapping("/save")
    @ApiOperation("保存用户")
    public String save(@RequestBody User user){
        return "入门小站";
    }

}
@Data
@NoArgsConstructor
@AllArgsConstructor
//描述实体类
@ApiModel("用戶信息")
class User {
    //描述实体类的属性
    @ApiModelProperty(value = "名字",name = "name",example = "入门小站")
    private String name;

    @ApiModelProperty(value = "年龄",name="age",example = "20")
    private Integer age;

    @ApiModelProperty(value = "地址",name="address",example = "rumenz.com")
    private String address;

    @ApiModelProperty(value = "邮箱",name="email",example = "[e-mail]")
    private String email;

}

在线测试接口可以点击Try it out填入相关参数测试。

本小结源码地址:

• GitHub:https://github.com/mifunc/springboot/tree/main/lession8
• Gitee:https://gitee.com/rumenz/springboot/tree/master/lession8
• https://rumenz.com/rumenbiji/springboot-swagger20-rumen.html

介绍

• 我的博客 https://rumenz.com/ ,
• 我的工具箱 https://tooltt.com/