随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染、先后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远。
这样后段开发好了api 之后就要提交api 文档给前端的朋友。给前端的api 文档各个公司有各个公司的要求,有的是word 有的是 md 文档,或者是 postman 的一个连接。
好了废话不多说说一下 swagger -ui 吧
什么是swagger
swagger是一个restful风格接口的文档在线自动生成和测试的框架
官方描述:the world's most popular framework for apis.
先看一下 swagger-ui 生成的api 的效果吧(这是一个增删改查的小李子)
然后我们打开查询所有用户的api 看到api 内容
然后在服务器运行的状态下点击 try it out 测试查询功能
接着打开新增的api 查看
好了这个就是自动生成的api 效果。接下来我们就看怎么在我们的项目中使用swagger-ui 吧
springboot 集成 swagger -ui
1、添加依赖
<dependency> <groupid>io.springfox</groupid> <artifactid>springfox-swagger2</artifactid> <version>2.2.2</version> </dependency> <dependency> <groupid>io.springfox</groupid> <artifactid>springfox-swagger-ui</artifactid> <version>2.2.2</version> </dependency>
2、编写配置文件
在application 同级目录新建 swagger2 文件
package com.abel.example; 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.spi.documentationtype; import springfox.documentation.spring.web.plugins.docket; import springfox.documentation.swagger2.annotations.enableswagger2; /** * created by yangyibo on 2018/9/7. */ @configuration @enableswagger2 public class swagger2 { /** * 创建api应用 * apiinfo() 增加api相关信息 * 通过select()函数返回一个apiselectorbuilder实例,用来控制哪些接口暴露给swagger来展现, * 本例采用指定扫描的包路径来定义指定要建立api的目录。 * @return */ @bean public docket createrestapi() { return new docket(documentationtype.swagger_2) .apiinfo(apiinfo()) .select() .apis(requesthandlerselectors.basepackage("com.abel.example.controller")) .paths(pathselectors.any()) .build(); } /** * 创建该api的基本信息(这些基本信息会展现在文档页面中) * 访问地址:http://项目实际地址/swagger-ui.html * @return */ private apiinfo apiinfo() { return new apiinfobuilder() .title("spring boot中使用swagger2构建restful apis") .description("更多请关注https://blog.csdn.net/u012373815") .termsofserviceurl("https://blog.csdn.net/u012373815") .contact("abel") .version("1.0") .build(); } }
3、在controller上添加注解,自动生成api
注意:
package com.abel.example.controller; import javax.servlet.http.httpservletrequest; import java.util.map; import com.abel.example.bean.user; import io.swagger.annotations.*; import org.apache.log4j.logger; import org.springframework.beans.factory.annotation.autowired; import org.springframework.http.httpstatus; import org.springframework.http.responseentity; import org.springframework.stereotype.controller; import org.springframework.web.bind.annotation.*; import com.abel.example.service.userservice; import com.abel.example.util.commonutil; @controller @requestmapping(value = "/users") @api(value = "用户的增删改查") public class usercontroller { @autowired private userservice userservice; /** * 查询所有的用户 * api :localhost:8099/users * @return */ @requestmapping(method = requestmethod.get) @responsebody @apioperation(value = "获取用户列表,目前没有分页") public responseentity<object> findall() { return new responseentity<>(userservice.listusers(), httpstatus.ok); } /** * 通过id 查找用户 * api :localhost:8099/users/1 * @param id * @return */ @requestmapping(value = "/{id}", method = requestmethod.get) @responsebody @apioperation(value = "通过id获取用户信息", notes="返回用户信息") public responseentity<object> getuserbyid(@pathvariable integer id) { return new responseentity<>(userservice.getuserbyid(long.valueof(id)), httpstatus.ok); } /** * 通过spring data jpa 调用方法 * api :localhost:8099/users/byname?username=xxx * 通过用户名查找用户 * @param request * @return */ @requestmapping(value = "/byname", method = requestmethod.get) @responsebody @apiimplicitparam(paramtype = "query",name= "username" ,value = "用户名",datatype = "string") @apioperation(value = "通过用户名获取用户信息", notes="返回用户信息") public responseentity<object> getuserbyusername(httpservletrequest request) { map<string, object> map = commonutil.getparametermap(request); string username = (string) map.get("username"); return new responseentity<>(userservice.getuserbyusername(username), httpstatus.ok); } /** * 通过spring data jpa 调用方法 * api :localhost:8099/users/byusernamecontain?username=xxx * 通过用户名模糊查询 * @param request * @return */ @requestmapping(value = "/byusernamecontain", method = requestmethod.get) @responsebody @apiimplicitparam(paramtype = "query",name= "username" ,value = "用户名",datatype = "string") @apioperation(value = "通过用户名模糊搜索用户信息", notes="返回用户信息") public responseentity<object> getusers(httpservletrequest request) { map<string, object> map = commonutil.getparametermap(request); string username = (string) map.get("username"); return new responseentity<>(userservice.getbyusernamecontaining(username), httpstatus.ok); } /** * 添加用户啊 * api :localhost:8099/users * @param user * @return */ @requestmapping(method = requestmethod.post) @responsebody @apimodelproperty(value="user",notes = "用户信息的json串") @apioperation(value = "新增用户", notes="返回新增的用户信息") public responseentity<object> saveuser(@requestbody user user) { return new responseentity<>(userservice.saveuser(user), httpstatus.ok); } /** * 修改用户信息 * api :localhost:8099/users * @param user * @return */ @requestmapping(method = requestmethod.put) @responsebody @apimodelproperty(value="user",notes = "修改后用户信息的json串") @apioperation(value = "新增用户", notes="返回新增的用户信息") public responseentity<object> updateuser(@requestbody user user) { return new responseentity<>(userservice.updateuser(user), httpstatus.ok); } /** * 通过id删除用户 * api :localhost:8099/users/2 * @param id * @return */ @requestmapping(value = "/{id}", method = requestmethod.delete) @responsebody @apioperation(value = "通过id删除用户信息", notes="返回删除状态1 成功 0 失败") public responseentity<object> deleteuser(@pathvariable integer id) { return new responseentity<>(userservice.removeuser(id.longvalue()), httpstatus.ok); } }
注解含义:
@api:用在类上,说明该类的作用。 @apioperation:注解来给api增加方法说明。 @apiimplicitparams : 用在方法上包含一组参数说明。 @apiimplicitparam:用来注解来给方法入参增加说明。 @apiresponses:用于表示一组响应 @apiresponse:用在@apiresponses中,一般用于表达一个错误的响应信息 code:数字,例如400 message:信息,例如"请求参数没填好" response:抛出异常的类 @apimodel:描述一个model的信息(一般用在请求参数无法使用@apiimplicitparam注解进行描述的时候) @apimodelproperty:描述一个model的属性
注意:@apiimplicitparam的参数说明:
paramtype会直接影响程序的运行期,如果paramtype与方法参数获取使用的注解不一致,会直接影响到参数的接收。
4、启动项目效果图:
服务器启动后访问 http://localhost:8099/swagger-ui.html 效果如下
点击查看效果
本文项目全部代码:https://github.com/527515025/springboot/tree/master/springboot-swagger-ui
总结
以上就是这篇文章的全部内容了,希望本文的内容对大家的学习或者工作具有一定的参考学习价值,谢谢大家对服务器之家的支持。如果你想了解更多相关内容请查看下面相关链接
原文链接:https://blog.csdn.net/u012373815/article/details/82685962