一、遇到的问题

作为一名coder,经常需要向别人提供接口,或者调用别人的接口。于是就有了接口参数是什么意思,要怎么传参数,返回值是什么意思……有多少调用方,就会有多少人来询问这些参数。如果是长时间之后,自己或许都不知道这些参数是什么意思。于是维护接口文档便成了一项必不可少的工作,维护文档也有很多问题:

  • 如果手工写会很费劲
  • 接口变更后可能会忘了同步文档
  • ……

二、Swagger配置

Swagger(官方文档)可以快速帮助实现接口api的维护与简单测试。

a、引入maven依赖包

    <dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.5.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.5.0</version>
</dependency>

b、配置Swagger

@Configuration
@EnableSwagger2
@Profile("dev")
public class SwaggerConfig {
public static final String SWAGGER_SCAN_BASE_PACKAGE = "api.doc.demo.controller";
public static final String VERSION = "1.0.0"; @Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
/**api接口包扫描路径*/
.apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
/**可以根据url路径设置哪些请求加入文档,忽略哪些请求*/
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
/**设置文档的标题*/
.title("Swagger2 接口文档示例")
/**设置文档的描述*/
.description("更多内容请关注:http://www.abc.com")
/**设置文档的联系方式*/
.contact(new Contact("create by XXX", "http://www.abc.com", "xxxx.@xxx.com"))
/**设置文档的License信息->1.3 License information*/
.termsOfServiceUrl("www.abc.com")
.license("xxx")
.licenseUrl("http://www.xxx.com")
/**设置文档的版本信息-> 1.1 Version information*/
.version(VERSION)
.build();
}
}

c、常用注解

  • @ApiOperation : api说明
    @ApiOperation(value="获取用户列表", notes="获取所有用户列表",produces = "application/json")
@RequestMapping(value="/getList", method= RequestMethod.GET)
public List<UserModel> getUserList() {
return getDemoList();
}

  • @ApiResponses :默认Response的基础上增加新的Response说明
  • @ApiImplicitParam : 描述接口参数
@ApiImplicitParam(name = "userId",value = "用户ID",dataType = "int",paramType = "path")
  • @ApiImplicitParams : 多个参数
@ApiImplicitParams({
@ApiImplicitParam(name = "id",value = "用户ID",paramType = "path",dataType = "int"),
@ApiImplicitParam(name = "userName",value = "用户名称",paramType = "form",dataType = "string")
})
  • @ApiModel : model属性
@ApiModel(value = "user", description = "user对象")
public class UserModel {
@ApiModelProperty(value = "ID", dataType = "Integer", required = true)
private Integer userId;
@ApiModelProperty(value = "用戶名", dataType = "String")
private String userName;
@ApiModelProperty(value = "性別", dataType = "Integer", allowableValues = "0,1,2")
private Integer sex;
}

这样就可以通过访问 http://localhost:8080/swagger-ui.html 看到接口API调用说明。demo

【工具】Swagger2写接口注释的更多相关文章

  1. Java的LockSupport工具,Condition接口和ConditionObject

    在之前我们文章(关于多线程编程基础和同步器),我们就接触到了LockSupport工具和Condition接口,之前使用LockSupport工具来唤醒阻塞的线程,使用Condition接口来实现线程 ...

  2. Spring Boot (十五): 优雅的使用 API 文档工具 Swagger2

    1. 引言 各位在开发的过程中肯定遇到过被接口文档折磨的经历,由于 RESTful 接口的轻量化以及低耦合性,我们在修改接口后文档更新不及时,导致接口的调用方(无论是前端还是后端)经常抱怨接口与文档不 ...

  3. 在Eclipse中怎样写Java注释

    java中的注释分为实现注释和文档注释 实现注释就是那些/……../和//……的注释,是注释程序用的,文档注释是/*……./的注释,是用来生成javadoc的.设置方法如下: 1.打开Eclipse的 ...

  4. 【百度地图API】如何在地图上添加标注?——另有:坐标拾取工具+打车费用接口介绍

    原文:[百度地图API]如何在地图上添加标注?--另有:坐标拾取工具+打车费用接口介绍 摘要: 在这篇文章中,你将学会,如何利用百度地图API进行标注.如何使用API新增的打车费用接口. ------ ...

  5. 前端必备之Node+mysql+ejs模版如何写接口

    前端必备之Node+mysql+ejs模版如何写接口 这星期公司要做一个视频的后台管理系统, 让我用Node+mysql+ejs配合写接口, 周末在家研究了一下, 趁还没来具体需求把研究内容在这里分享 ...

  6. node+pm2+express+mysql+sequelize来搭建网站和写接口

    前面的话:在这里已经提到了安装node的方法,node是自带npm的.我在技术中会用es6去编写,然后下面会分别介绍node.pm2.express.mysql.sequelize.有少部分是摘抄大佬 ...

  7. Springboot集成swagger2生成接口文档

    [转载请注明]: 原文出处:https://www.cnblogs.com/jstarseven/p/11509884.html    作者:jstarseven    码字挺辛苦的.....   一 ...

  8. Java后端开发工作 - 写接口

    我在公司的工作内容是,对于一个BS应用,负责服务器端开发工作,Java语言.与前端开发人员合作,最终提供给前端RESTFUL接口,保证页面正常响应. 经验之谈 一个接口可以理解为一个业务逻辑,一个业务 ...

  9. 「快学springboot」16.让swagger帮忙写接口文档

    swagger简介 官方的介绍 THE WORLD'S MOST POPULAR API TOOLING Swagger is the world's largest framework of API ...

随机推荐

  1. JSON-Server 安装

    在后台还没给接口之前,使用JSON-Server搭建一台JSON服务器,将接口要返回的数据放在json文件里面.然后请求这些数据,这样我们可以先做一些东西,等后台接口好了之后直接替换就可以了,不必一直 ...

  2. angular2+ 引用layDate日期选择插件

    layDate日期选择插件使用npm安装好像是行不通的,但angular2+的日期选择控件库又不能够支持时分秒的选择 在angular项目中引用layDate 1. 首先官网下载layDate独立版, ...

  3. 160309、Spring AOP操作action时无法注入,报空指针错误

    今天帮同事看个问题,action注入失败,代码没问题,主要是stuts2权限移交的问题,特此记录一下 Spring AOP操作action时无法注入,报NullPointer异常 当使用Spring ...

  4. wf-删除所选

    w框架-结合用户的不同点击路径,提交正确的id集合. <table class="table"> <tr> <td></td> &l ...

  5. Python多股票同周期可视化

    import warnings warnings.filterwarnings("ignore") import numpy as np import pandas as pd i ...

  6. HDFS基本操作的API

    一.从hdfs下载文件到windows本地: package com.css.hdfs01; import java.io.IOException; import java.net.URI; impo ...

  7. 前端构建工具gulpjs的使用介绍及技巧(一)

    原文链接:http://www.cnblogs.com/2050/p/4198792.html gulpjs是一个前端构建工具,与gruntjs相比,gulpjs无需写一大堆繁杂的配置参数,API也非 ...

  8. 基于flask的代码上传

    from flask import Flask,Blueprint,request,render_template from flask import current_app as app from ...

  9. JSP学习(第二课)

    把GET方式改为POST在地址栏上就不会显示. 发现乱码了,设置编码格式(这个必须和reg.jsp中page的charset一致):  但是注意了!我们传中文名,就会乱码: 通过get方式提交的请求无 ...

  10. js 屏蔽浏览器右键菜单

    <script type="text/javascript"> function doNothing(){ window.event.returnValue=false ...