乐趣区

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

jiezi

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", "xenry@163.com");
        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", "xenry@163.com");
        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 = "372669319@qq.com")
    private String email;

}

在线测试接口能够点击 Try it out 填入相干参数测试。

本小结源码地址:

  • GitHub:https://github.com/mifunc/spr…
  • Gitee:https://gitee.com/rumenz/spri…
  • https://rumenz.com/rumenbiji/…

介绍

  • 我的博客 https://rumenz.com/ ,
  • 我的工具箱 https://tooltt.com/
  • 微信公众号:【入门小站】

  • 关注【入门小站】回复【1001】获取 linux 常用命令速查手册
  • 关注【入门小站】回复【1003】获取 LeetCode 题解【java 语言实现】
  • 关注【入门小站】回复【1004】获取 Java 根底外围总结
  • 关注【入门小站】回复【1009】获取 阿里巴巴 Java 开发手册
退出移动版