个人中心
gpt4 book ai didi

Java利用Swagger2自动生成对外接口的文档

转载 作者：qq735679552 更新时间：2022-09-28 22:32:09 29 4
gpt4 key购买 nike

CFSDN坚持开源创造价值，我们致力于搭建一个资源共享平台，让每一个IT人在这里找到属于你的精彩世界.

这篇CFSDN的博客文章Java利用Swagger2自动生成对外接口的文档由作者收集整理，如果你对这篇文章有兴趣，记得点赞哟.

一直以来做对外的接口文档都比较原始，基本上都是手写的文档传来传去，最近发现了一个新玩具，可以在接口上省去不少麻烦.

swagger是一款方便展示的api文档框架。它可以将接口的类型最全面的展示给对方开发人员，避免了手写文档的片面和误差行为.

swagger目前有两种swagger和swagger2两种，1比较麻烦，所以不考虑使用。本文主要记录我用swagger2做对外接口的两种方式，方面后面查阅.

1、使用传统的springmvc整合swagger2 。

1、maven依赖 。

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
<!--springfox依赖-->
     <dependency>
       <groupid>com.fasterxml.jackson.core</groupid>
       <artifactid>jackson-core</artifactid>
       <version> 2.8 . 0 </version>
     </dependency>
     <dependency>
       <groupid>com.fasterxml.jackson.core</groupid>
       <artifactid>jackson-databind</artifactid>
       <version> 2.6 . 3 </version>
     </dependency>
     <dependency>
       <groupid>com.fasterxml.jackson.core</groupid>
       <artifactid>jackson-annotations</artifactid>
       <version> 2.6 . 3 </version>
     </dependency>
     <dependency>
       <groupid>io.springfox</groupid>
       <artifactid>springfox-swagger2</artifactid>
       <version> 2.4 . 0 </version>
     </dependency>
     <dependency>
       <groupid>io.springfox</groupid>
       <artifactid>springfox-swagger-ui</artifactid>
       <version> 2.4 . 0 </version>
     </dependency>

2、spring-mvc.xml 中添加映射静态的配置（其实我项目中把这个去掉也可以，不知道什么情况）:

?
1
2
3
<!-- swagger静态文件路径 -->
   <mvc:resources location= "classpath:/meta-inf/resources/" mapping= "swagger-ui.html" />
   <mvc:resources location= "classpath:/meta-inf/resources/webjars/" mapping= "/webjars/**" />

注意：基本的springmvc配置我就不贴了，需要注意的是，如果你看到swagger-ui.html 界面出来，但却一片空白，请检查下你web.xml中拦截器的配置，一定要springmvc先拦截到，然后界面才会显示的.

3、然后是swagger2的配置类:

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
@configuration
@enableswagger2
public class swaggerconfig extends webmvcconfigurationsupport {
 
   @bean
   public docket createrestapi() {
     return new docket(documentationtype.swagger_2)
         .apiinfo(apiinfo())
         .select()
         .apis(requesthandlerselectors.basepackage( "net.laoyeyey.yyblog" ))
         .paths(pathselectors.any())
         .build();
   }
 
   private apiinfo apiinfo() {
     return new apiinfobuilder()
         .title( "yyblog项目 restful apis" )
         .description( "yyblog项目api接口文档" )
         .version( "1.0" )
         .build();
   }
}

注意：paths如果在生产情况下可以调整为pathselectors.none()，即不显示所有接口信息； 。

4、接口信息配置 。

即在springmvc的controller中配置相关的接口信息 。

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
@controller
@requestmapping (value = "aitou" )
@api (description = "测试服务-账户信息查询" )
public class dailyoperationdatacontroller {
   logger      logger  = logger.getlogger(dailyoperationdatacontroller. class );
   @autowired
   private dailyoperationdataservice dailyoperationdataservice;
   /*
    * @apioperation(value = "接口说明", httpmethod ="接口请求方式", response ="接口返回参数类型", notes ="接口发布说明"
    * @apiparam(required = "是否必须参数", name ="参数名称", value ="参数具体描述"
　　　*/
   @apioperation (value = "账户信息查询接口" )
   @requestmapping (method ={requestmethod.post,requestmethod.get}, value= "/query/dailydata/{datadate}" )
   @responsebody
   public dailyoperationdatadto getdailyreportbydatadate( @pathvariable ( "datadate" ) string datadate) {
     try {
       return dailyoperationdataservice.getdailyreportbydatadate(datadate);
     } catch (exception e) {
       logger.error(e.getmessage(), e);
     }
 
     return null ;
   }
 
}

注：通常情况下swagger2会将扫描包下所有的接口展示出来，这里我是对外的接口是单独一个包，避免展示过多的接口，当然接口方法也可以让它不展示。可以在下面看到相关的注解中有写.

常用的一些注解 。

@api：用在类上，说明该类的作用 @apioperation：用在方法上，说明方法的作用 @apiimplicitparams：用在方法上包含一组参数说明 @apiimplicitparam：用在 @apiimplicitparams 注解中，指定一个请求参数的各个方面 　　paramtype：参数放在哪个地方 　　· header --> 请求参数的获取：@requestheader 　　· query -->请求参数的获取：@requestparam 　　· path（用于restful接口）--> 请求参数的获取：@pathvariable 　　· body（不常用） 　　· form（不常用） 　　name：参数名 　　datatype：参数类型 　　required：参数是否必须传 　　value：参数的意思 　　defaultvalue：参数的默认值 @apiresponses：用于表示一组响应 @apiresponse：用在@apiresponses中，一般用于表达一个错误的响应信息 　　code：数字，例如400 　　message：信息，例如"请求参数没填好" 　　response：抛出异常的类 @apiparam：单个参数描述 @apimodel：描述一个model的信息，用对象来接收参数（这种一般用在post创建的时候，使用@requestbody这样的场景，请求参数无法使用@apiimplicitparam注解进行描述的时候） @apimodelproperty：描述一个model的属性 @apiproperty：用对象接收参数时，描述对象的一个字段 @apiignore：使用该注解忽略这个api 。

基本上就是上面这些了，是不是很easy，下面看下效果图 。

Java利用Swagger2自动生成对外接口的文档

Java利用Swagger2自动生成对外接口的文档

2、使用springboot整合swagger2 。

上面说了使用传统的springmvc整合swagger2，在说说最近比较流行的springboot的方式，其实原理都是一样的.

1、maven依赖 。

?
1
2
3
4
5
6
7
8
9
10
11
<!--springfox依赖 -->
     <dependency>
       <groupid>io.springfox</groupid>
       <artifactid>springfox-swagger2</artifactid>
       <version> 2.7 . 0 </version>
     </dependency>
     <dependency>
       <groupid>io.springfox</groupid>
       <artifactid>springfox-swagger-ui</artifactid>
       <version> 2.7 . 0 </version>
     </dependency>

这个是我最近用springboot写的个人项目中的内用，版本用的2.7.0 。

2、添加静态资源配置 。

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
@configuration
public class webmvcconfig extends webmvcconfigureradapter { /**
    * 配置静态资源路径以及上传文件的路径
    *
    * @param registry
    */
   @override
   public void addresourcehandlers(resourcehandlerregistry registry) {
     registry.addresourcehandler( "/static/**" ).addresourcelocations( "classpath:/static/" );
     registry.addresourcehandler( "/upload/**" ).addresourcelocations(environment.getproperty( "spring.resources.static-locations" ));
     /*swagger-ui*/
     registry.addresourcehandler( "swagger-ui.html" ).addresourcelocations( "classpath:/meta-inf/resources/" );
     registry.addresourcehandler( "/webjars/**" ).addresourcelocations( "classpath:/meta-inf/resources/webjars/" );
   }
 
}

其实就是最后两句，如果你不配置这个的话，访问swagger-ui.html会出现500，还是404的错误来着，记不清了，应该是404. 。

3、swagger2的配置类 。

和上面一样，基本上没区别 。

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
@configuration
@enableswagger2
@enablewebmvc
public class swaggerconfig extends webmvcconfigurationsupport {
 
   @bean
   public docket createrestapi() {
     return new docket(documentationtype.swagger_2)
         .apiinfo(apiinfo())
         .select()
         .apis(requesthandlerselectors.basepackage( "net.laoyeye.yyblog.web.frontend" ))
         .paths(pathselectors.none())
         .build();
   }
 
   private apiinfo apiinfo() {
     return new apiinfobuilder()
         .title( "yyblog项目 restful apis" )
         .description( "yyblog项目api接口文档" )
         .version( "1.0" )
         .build();
   }
 
 
}

注意，我上面有说path的问题哦，直接拷贝不显示api的，(#^.^#) 。

4、接口的配置 。

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
/**
  * 前台文章controller
  * @author 小卖铺的老爷爷
  * @date 2018年5月5日
  * @website www.laoyeye.net
  */
@api (description= "文章查询" )
@controller
@requestmapping ( "/article" )
public class articlecontroller {
   @autowired
   private articleservice articleservice;
   @autowired
   private settingservice settingservice;
   @autowired
   private cateservice cateservice;
   @autowired
   private tagreferservice tagreferservice;
   @autowired
   private userservice userservice;
   @autowired
   private articlemapper articlemapper;
   @autowired
   private commentservice commentservice;
  
   @apioperation (value= "文章查询接口" )
   @apiimplicitparam (name = "id" , value = "文章id" , required = true , datatype = "long" )
   @getmapping ( "/{id}" )
   public string index(model model, @pathvariable ( "id" ) long id) {
     try {
       articleservice.updateviewsbyid(id);
     } catch (exception ignore) {
     }
     list<setting> settings = settingservice.listall();
     map<string,object> map = new hashmap<string,object>();
     for (setting setting : settings) {
       map.put(setting.getcode(), setting.getvalue());
     }
     article article = articleservice.getarticlebyid(id);
     model.addattribute( "settings" , map);
     model.addattribute( "catelist" , cateservice.listallcate());
     model.addattribute( "article" , article);
     model.addattribute( "tags" , tagreferservice.listnamebyarticleid(article.getid()));
     model.addattribute( "author" , userservice.getnicknamebyid(article.getauthorid()));
     //回头改
     model.addattribute( "articles" , articlemapper.listarticlebytitle( null ));
     model.addattribute( "similars" , articlemapper.listarticlebytitle( null ));
     commentquery query = new commentquery();
     query.setlimit( 10 );
     query.setpage( 1 );
     query.setarticleid(id);
     model.addattribute( "comments" , commentservice.listcommentbyarticleid(query));
     return "frontend/article" ;
   }
  
   @apioperation (value= "文章评论查询接口" )
   @postmapping ( "/comments" )
   @responsebody
   public datagridresult comments(commentquery query) {
     //设置默认10
     query.setlimit( 10 );
     return commentservice.listcommentbyarticleid(query);
   }
  
   @apioperation (value= "文章点赞接口" )
   @apiimplicitparam (name = "articleid" , value = "文章id" , required = true , datatype = "long" )
   @postmapping ( "/approve" )
   @responsebody
   public yyblogresult approve( @requestparam long articleid) {
     return articleservice.updateapprovecntbyid(articleid);
   }
}

最后同样来个效果图，和上面一样.

pathselectors.none()的时候 。

Java利用Swagger2自动生成对外接口的文档

pathselectors.any()的时候 。

Java利用Swagger2自动生成对外接口的文档

Java利用Swagger2自动生成对外接口的文档

看到效果图是不是接口内容一目了然，很简洁明了了.

最后，好像忘记说swagger文档的路径了 。

如果你的项目在根目录：http://localhost:8080/swagger-ui.html 。

如果不是根目录那就是：http://localhost:8080/你的项目名/swagger-ui.html 。

以上就是本文的全部内容，希望对大家的学习有所帮助，也希望大家多多支持我.

原文链接：http://www.cnblogs.com/laoyeye/p/9047504.html 。

最后此篇关于Java利用Swagger2自动生成对外接口的文档的文章就讲到这里了,如果你想了解更多关于Java利用Swagger2自动生成对外接口的文档的内容请搜索CFSDN的文章或继续浏览相关文章，希望大家以后支持我的博客！ 。

29 4 0
文章推荐： Java类（接口）的新类型-密封类
文章推荐： 糟糕程序员的20个坏习惯
文章推荐： redis实现共同好友的思路详解
文章推荐： 详解Redis瘦身指南
qq735679552
个人简介

我是一名优秀的程序员,十分优秀！

滴滴打车优惠券免费领取
滴滴打车优惠券
全站热门文章
Copyright 2021 - 2024 cfsdn All Rights Reserved 蜀ICP备2022000587号
广告合作:1813099741@qq.com 6ren.com