SpringBoot使用Swagger2

java8

帖子摘要：SpringBoot使用Swagger2 1.引入swagger依赖2.添加swagger配置类3.测试Controller4.测试5.swagger的注解Api注解ApiOperation注解Api......
6 w( ^5 O1 x/ j3 }1 Z  c+ D
8 s: u) \7 V# R! t, K大家好，欢迎来到Java吧（www.java8.com），交流、学习Java技术、获取Java资源无任何套路，今天说一说：“SpringBoot使用Swagger2”
9 f& ~: D7 l0 D$ P9 Z" k& [7 D1 x2 O
# J" W( Y7 T' j0 I( s3 C( H% k& n
        
( o+ A0 P3 Z  s  y$ F; }0 U& ^               
                    
                        
                    
) Y$ {, c$ f- r# [2 E8 E' b                    
SpringBoot使用Swagger2
+ j' U. W" y% j3 h& `& z+ u& [

1.引入swagger依赖

2.添加swagger配置类

3.测试Controller

4.测试

5.swagger的注解

Api注解

ApiOperation注解

ApiImplicitParam、ApiImplicitParams注解

ApiParam注解

ApiResponse、ApiResponses注解

ResponseHeader注解

ApiModel、ApiModelProperty注解
5 t- I6 l" O: t' A8 T3 j; O( l  

6.更多
% p; k$ b7 `4 x! H$ G  J+ m
1.引入swagger依赖
5 F' l4 g2 g( T2 o+ P

        
5 x1 c% l( O. A
            io.springfox
            springfox-swagger2
            2.9.2
        
        
% g, b3 [6 o6 f) G# U' }) I  q8 {# G
            io.springfox
            springfox-swagger-ui
            2.9.2
9 ^  P6 @8 x8 r6 Q9 C! c
        
复制代码

2.添加swagger配置类

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
! z2 ?6 y+ o% Q1 j8 j
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
2 D  `* d4 V# h6 e* W7 @
import springfox.documentation.service.ApiInfo;
2 C, {# n3 C) q( R  j3 v; n+ G
import springfox.documentation.spi.DocumentationType;
0 i2 Y6 U5 ?$ b: r) D
import springfox.documentation.spring.web.plugins.Docket;
: k3 S/ e" b0 ~" h* G! J6 \0 A4 P6 g
import springfox.documentation.swagger2.annotations.EnableSwagger2;
& s+ I0 U0 }0 e5 K# b0 a7 g
@Configuration
$ K0 S; C9 u% E' v
@EnableSwagger2
public class SwaggerConfig {
0 N5 A1 P- L/ @1 m* W/ C* s! G
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                
. V: I+ G; P; a6 ^
                //swagger文档扫描的包这里扫描的是全部
/ G% j6 T( R$ C5 t; r1 H  b
                //如果扫描指定包下的可以这样写
4 A, p% y; h7 I5 R+ ^2 X
                //.apis(RequestHandlerSelectors.basePackage("com.xxx.yyy.controller"))
                        .apis(RequestHandlerSelectors.any())
. g3 Q( K( v6 Y. p
                .paths(PathSelectors.any())
                .build();
    }
8 X5 y& H- n! ~3 A
    private ApiInfo apiInfo(){
+ {. `: z* i# s7 i* M
        return new ApiInfoBuilder()
( g, ]/ j" o7 c  W) w
                .title("标题")
0 i% M# X5 p4 ]8 b, v: z8 X. a) X" H4 C/ ~
                .description("描述")
                .version("版本")
% y) a4 j2 X; E( T* d6 t  \+ P4 v
                .termsOfServiceUrl("公司网址")
                .build();
) ?. k" A' E+ f9 F1 r, |
    }
2 b; S1 U9 Q7 x- a2 S' M
}
+ |+ ]+ Q, g9 w: a2 e7 Z
复制代码

3.测试Controller

@RestController
@RequestMapping("/test")
public class TestController {
2 D1 b' U- Q- D
    @GetMapping("/test01")
) Z3 f  h8 b7 D
    public String test01(){
        return "test01";
    }
+ v* v' N3 l5 Q* Q& b% y' p* Z% v
    @GetMapping("/test02")
8 Q! l% e$ ~! U5 @  Z0 y  c
    public String test02(){
* ~9 ^2 T2 j! p6 n( Q
        return "test02";
    }
    @GetMapping("/test03")
5 l: F4 b6 H5 s8 R! G
    public String test03(){
        return "test03";
& K& K  K# o: |# C9 }
    }
}
2 S# y" v, q2 ~6 J* I- p
复制代码

4.测试
( K2 ~3 R) @; `( d' V" ?项目正常启动后浏览器输入网址
7 t* `7 S5 @' g9 T6 A9 R7 N http://localhost:8100/swagger-ui.html#/
( l" _/ X9 P. Z# N
4 S! [8 x0 D& a) a[color=]这里的端口填写自己服务的端口我的是8100默认端口8080

a285a0ba195a48489b734dde0ba8a689.png (69.27 KB, 下载次数: 0, 售价: 2 金钱)

2023-1-19 12:24 上传

点击文件名下载附件
a285a0ba195a48489b734dde0ba8a689.png

7169aefbc1924741bd62665bf43e1753.png (32.64 KB, 下载次数: 0, 售价: 3 金钱)

2023-1-19 12:24 上传

点击文件名下载附件
7169aefbc1924741bd62665bf43e1753.png

08020acac6194492a6bf351b801efea3.png (38.09 KB, 下载次数: 0, 售价: 3 金钱)

2023-1-19 12:24 上传

点击文件名下载附件
08020acac6194492a6bf351b801efea3.png

9 N- K, W9 |( N- C1 d; ]4 a( }

5e3c777276a0414db0aec11717cb7695.png (42.67 KB, 下载次数: 0, 售价: 4 金钱)

2023-1-19 12:24 上传

点击文件名下载附件
5e3c777276a0414db0aec11717cb7695.png

测试结果

43b6264629e34e398ac16d1caa193288.png (66.59 KB, 下载次数: 0, 售价: 3 金钱)

2023-1-19 12:24 上传

点击文件名下载附件
43b6264629e34e398ac16d1caa193288.png

5.swagger的注解
上面就是swagger的基本使用
但swagger也提供了一些注解这里例举一些常用注解

' |0 s5 ^/ R; r) l) xApi注解
2 C. k$ j0 i$ u" ?6 n" H/ M, f       用于标记当前类为Swagger的文档资源。其中含有几个常用属性分别说明如下。


0 ~! v# v/ r5 W, b6 C+ M1 X1 @7 o ?　value定义当前接口文档的名称。
1 S7 I7 L! d7 Z, i6 C$ n( e0 x3 i3 n ?　description用于定义当前接口文档的介绍。
& f( h1 P& d1 @* G7 R, R
; ?. q9 @, C6 o1 G* v# V) w! x

@Api(value = "controller接口",description = "用户测试接口")
public class TestController {
复制代码

3 _: \9 k/ E) i0 c7 Q& E

92b6e679380c4892ba145b9e4b67f232.png (37.46 KB, 下载次数: 0, 售价: 2 金钱)

2023-1-19 12:24 上传

点击文件名下载附件
92b6e679380c4892ba145b9e4b67f232.png

+ b! h4 w, g+ R" S* A/ eApiOperation注解
9 c! n" o5 O) i" l- Z3 w* B) P       @ApiOperation用在接口的方法上主要用来注解请求接口。其中包含几个常用属性分别说明如下。
! X" d! d  U7 r2 {

! ?7 e/ w0 x4 ?4 `; x5 }! Z$ ] ?　value对API的简短描述。
?　noteAPI的有关细节描述。
1 n# a5 V) f! S4 ^ ?　hidden如果值为true就会在文档中隐藏。
$ n% k6 z7 _, b. \. C! _
6 ~: I; J+ X, S" k* @
演示

8 j2 x3 U  b# G

    @GetMapping("/test01")
8 C0 i. r5 X$ P
    @ApiOperation(value = "测试方法01",notes = "细节的描述细节的测试",hidden = false)
    public String test01(){
: d& J6 @  ]: |' Y( }' U" O
        return "test01";
" b, \0 Z* h" X. b% y4 \
    }
1 p  L& C, m) P5 e; S2 G
复制代码

( J, W0 T& t( z1 F

656008a828014a3fbf41d7a094b877e5.png (29 KB, 下载次数: 0, 售价: 3 金钱)

2023-1-19 12:24 上传

点击文件名下载附件
656008a828014a3fbf41d7a094b877e5.png

% D7 `1 A, p9 gApiImplicitParam、ApiImplicitParams注解
       使用在API请求方法上@ApiImplicitParams的子集是@ApiImplicitParam注解其中@ApiImplicitParam注解常用参数。

0 u! D, p$ S& R& b$ q+ E
8 l( f6 i" E* l8 b4 z7 Y ?　name参数的名称。
* j8 |$ S7 P/ A& P' q2 Z ?　value参数值。
?　required如果值为true就是必传字段。
?　defaultValue参数的默认值。
& Z. c0 }" I: d; [ ?　dataType数据的类型。


  r- U5 ?" N3 [, C4 N: ?5 E演示

6 f  `! {& Z; ?0 g

    @GetMapping("/test02")
- m  k! Q  d* P4 c+ }0 u' k
    @ApiImplicitParams(value = {
            @ApiImplicitParam(name = "name",value = "测试姓名",required = false,defaultValue = "默认姓名李四"),
            @ApiImplicitParam(name = "age",value = "测试年龄",required = false,dataType = "Integer",defaultValue = "200")
5 |# t' g; J1 W1 l
    })
    public String test02(String name,Integer age){
        return "test02  姓名"+name+"  年龄:"+age;
, y6 O9 |. E- y
    }
复制代码

( a8 m, _% M( Y4 A8 p4 P; `% C

bd262f0a73c24240ac94ee3ba75e54bb.png (51.78 KB, 下载次数: 0, 售价: 4 金钱)

2023-1-19 12:24 上传

点击文件名下载附件
bd262f0a73c24240ac94ee3ba75e54bb.png

256f0a78fd0e445ba6367678ca7ec1f0.png (47.49 KB, 下载次数: 0, 售价: 1 金钱)

2023-1-19 12:24 上传

点击文件名下载附件
256f0a78fd0e445ba6367678ca7ec1f0.png

37063794e6ed48018e90dc26388dd149.png (62.52 KB, 下载次数: 0, 售价: 4 金钱)

2023-1-19 12:24 上传

点击文件名下载附件
37063794e6ed48018e90dc26388dd149.png

5 {1 Y* D* E# I, X" D0 r
8 L/ W+ @& Z* t$ LApiParam注解
6 g  ^6 {7 V7 E* S  I3 J       ApiParam用于方法的参数其中包含以下几个常用属性。


7 c* h# U1 c2 w3 F* Q2 g ?　name参数的名称。
3 m+ u/ O* c! k8 @ ?　value参数值。
?　required如果值为true就是必传字段。
?　defaultValue参数的默认值。
4 H% {. @' B5 Y1 M8 G ?　type参数的类型。
?　hidden如果值为true就隐藏这个参数。
, q" z/ E6 M/ t2 ?. F

与ApiImplicitParam、ApiImplicitParams注解类似不再赘述。
# h* I: u. z$ m. S2 l6 [  u
7 V8 W9 c5 j$ }% RApiResponse、ApiResponses注解
       @ApiResponses和@ApiResponse二者配合使用返回HTTP状态码。@ApiResponses的value值是@ApiResponse的集合多个@ApiResponse用逗号分隔。其中@ApiResponse常用参数如下。


?　codeHTTP状态码。
2 b2 s) g1 M2 H8 A; e ?　messageHTTP状态信息。
?　responseHeadersHTTP响应头。


' o3 b2 H+ b/ \7 l' k, ?. k演示

9 f( J7 L! K9 ]  f& t

@GetMapping("/test03")
# h# G6 f4 i# V- _) E
    @ApiResponses(value = {
            @ApiResponse(code = 200,message = "成功"),
            @ApiResponse(code = 404,message = "异常")
8 k: i& g) h' @0 N
    })
( h  Y3 c7 z' Q
    public String test03(){
  ]  o8 F# q  ^% W2 ^
        return "test03";
    }
复制代码

0 }/ s2 h4 g. X4 p- s" L  K0 n

86c9bda377204f9a8bef92fe5b5a4cf2.png (29.24 KB, 下载次数: 0, 售价: 2 金钱)

2023-1-19 12:24 上传

点击文件名下载附件
86c9bda377204f9a8bef92fe5b5a4cf2.png

2 C$ Z- k& r5 O- f9 t( J* p
2 A6 k! [! `; KResponseHeader注解
       如果需要设置响应头就将@ResponseHeader设置到@ApiResponse的responseHeaders参数中。@ResponseHeader提供了以下几个参数。


?　name响应头名称。
8 A+ K3 U% n" W1 c) |- }. D: L/ V ?　description响应头描述。
3 m' }( j& m0 |3 h  t, g
$ w. b* Z: p. j8 n$ M5 @: X
) l5 S( T' E) @* f2 I& D* s0 `ApiModel、ApiModelProperty注解
+ Y7 P9 n. _; I. y       设置API响应的实体类用作API返回对象。@ApiModel常用参数。
! G! q& l5 G' k4 }' p% r" ^" N
! W( n1 }) t" c. \" L. N; ~
?　value实体类名称。
8 ]1 K/ H! x$ m/ S) ~- k" y/ S, o ?　description实体类描述。


; Z0 g2 K/ h# G8 N       设置API响应实体的属性其中常用参数。
# `) i- |7 y  ~9 }4 Y

?　name属性名称。
?　value属性值。
8 H  R7 b& m1 M# L+ A8 R1 O

演示

@ApiModel(value = "Student(学生类)",description = "记录学生个人信息")
public class Student {

: r' s7 I$ `8 I3 J4 D6 I
    public String name;
    @ApiModelProperty(name = "age",value = "年龄")
    public Integer age;
$ O+ L4 w7 L+ @* N
}
复制代码

16d900d187bb41b98418b90f6fb9ee8f.png (53.65 KB, 下载次数: 0, 售价: 2 金钱)

2023-1-19 12:24 上传

点击文件名下载附件
16d900d187bb41b98418b90f6fb9ee8f.png

+ X) `% L, l# R, j
* @9 R3 j# P* p$ M& W) M9 b6.更多
本文总结粗略
更多详细使用参照swagger官网

! c8 C) c! b* M官方网站https://swagger.io/
: _* e& M1 C- P8 P/ _" c
9 m9 }0 `; N* }2 Q) @官方文档https://swagger.io/docs/
6 _2 z8 m1 Z. c  }* {) H               
* a! f9 M, n' k/ O; \' Z( d$ g               
. ~: G. X5 @0 c3 h" ?2 h5 ]               
本文来源csdn，由Java吧转载发布，观点不代表Java吧的立场，转载请标明来源出处：https://www.java8.com