SpringBoot+Swagger-ui自动生成API文档

随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染、先后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远。

这样后段开发好了api 之后就要提交api 文档给前端的朋友。给前端的api 文档各个公司有各个公司的要求,有的是word 有的是 md 文档,或者是 postman 的一个连接。

好了废话不多说说一下 swagger -ui 吧

什么是Swagger

Swagger是一个Restful风格接口的文档在线自动生成和测试的框架

官网:http://swagger.io

官方描述: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

总结

以上就是这篇文章的全部内容了,希望本文的内容对大家的学习或者工作具有一定的参考学习价值,谢谢大家对我们的支持。如果你想了解更多相关内容请查看下面相关链接

(0)

相关推荐

  • spring-boot 禁用swagger的方法

    在使用spring-boot开发的时候,我们很多时候会使用swagger作为api文档输出.可以在UI界面上看到api的路径,参数等等. 当然,作为开发环境是很方便的,但是上生产环境的时候,我们需要把swagger禁掉.怎么通过配置文件的方法来禁用swagger呢? 代码如下: import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.cont

  • Spring Boot整合Swagger2的完整步骤详解

    前言 swagger,中文"拽"的意思.它是一个功能强大的api框架,它的集成非常简单,不仅提供了在线文档的查阅, 而且还提供了在线文档的测试.另外swagger很容易构建restful风格的api. 一.Swagger概述 Swagger是一组围绕OpenAPI规范构建的开源工具,可帮助设计.构建.记录和使用REST API. 简单说下,它的出现就是为了方便进行测试后台的restful形式的接口,实现动态的更新,当我们在后台的接口 修改了后,swagger可以实现自动的更新,而不需要

  • 详解SpringBoot结合swagger2快速生成简单的接口文档

    1. pom.xml中加入依赖 <dependency> <groupId>com.spring4all</groupId> <artifactId>swagger-spring-boot-starter</artifactId> <version>1.8.0.RELEASE</version> </dependency> 2. 在启动类(即带@SpringBootApplication这个注解的类)上添加@E

  • SpringBoot整合Swagger2实例方法

    在进行软件开发的时候免不了要写接口文档,这些文档需要明确写出接口的类型.请求的URL.传参和返回值格式等信息,用于和前端交互或者提供给测试进行接口测试.但是手写文档一方面带给我们很大的工作量,另一方面如果接口有变更则需要频繁修改并且发给相关的人,无形中增加了工作量.小编为大家介绍一个生成文档的工具Swagger,上手简单,学习成本低,非常适合开发SpringBoot项目,现在就跟着小编一起学习吧. 首先需要在pom文件中加入swagger2的依赖,依赖的jar包如下图所示. <dependenc

  • Springboot引入拦截器并放行swagger代码实例

    这篇文章主要介绍了Springboot引入拦截器并放行swagger代码实例,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下 Springboot引入拦截器 自定义的拦截器类 Interceptor package cn.zytao.taosir.auth.config; import javax.annotation.Resource; import javax.servlet.http.HttpServletRequest; import j

  • SpringBoot整合Swagger和Actuator的使用教程详解

    前言 本篇文章主要介绍的是SpringBoot整合Swagger(API文档生成框架)和SpringBoot整合Actuator(项目监控)使用教程. SpringBoot整合Swagger 说明:如果想直接获取工程那么可以直接跳到底部,通过链接下载工程代码. Swagger 介绍 Swagger 是一套基于 OpenAPI 规范构建的开源工具,可以帮助我们设计.构建.记录以及使用 Rest API.Swagger 主要包含了以下三个部分: Swagger Editor:基于浏览器的编辑器,我们

  • 详谈springboot过滤器和拦截器的实现及区别

    前言 springmvc中有两种很普遍的AOP实现: 1.过滤器(Filter) 2.拦截器(Interceptor) 本篇面对的是一些刚接触springboot的人群 所以主要讲解filter和interceptor的简单实现和它们之间到底有什么区别 (一些复杂的功能我会之后发出文章,请记得关注) Filter的简单实现 字面意思:过滤器就是过滤的作用,在web开发中过滤一些我们指定的url 那么它能帮我们过滤什么呢? 那功能可就多了: 比如过拦截掉我们不需要的接口请求 修改请求(reques

  • SpringBoot结合Swagger2自动生成api文档的方法

    首先在pom.xml中添加如下依赖,其它web,lombok等依赖自行添加 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version> </dependency> <dependency> <groupId>io.spri

  • SpringBoot+Swagger-ui自动生成API文档

    随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染.先后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远. 这样后段开发好了api 之后就要提交api 文档给前端的朋友.给前端的api 文档各个公司有各个公司的要求,有的是word 有的是 md 文档,或者是 postman 的一个连接. 好了废话不多说说一下 swagger -ui 吧 什么是Swagger Swagger是一个Restful风格接口的文档在线自动生成和测试的框架 官网:http://swag

  • SpringBoot如何自动生成API文档详解

    前言 在做项目的时候,如果项目是前后分离的,后端一定要和前端或者是移动端对接接口,那么问题来了,接口是不是要自己写给他们看,一般的会采用Excel或者Word来写,高级一点的就采用API管理平台手工录入,一个项目有上千上万个接口,天啊,这是多么大的工作量,在接口维护的时候更加痛苦,为了解决这样的事我们可以借助 japi这个项目来完成RESTFul文档的自动生成,完全基于注释生成,更多详细配置可查看https://github.com/dounine/japi. 使用说明 克隆项目下来 git c

  • Django restful framework生成API文档过程详解

    自动生成api文档(不管是函数视图还是类视图都能显示) 1.安装rest_framework_swagger库 pip install django-rest-swagger 2.在项目下的 urls.py 中加入如下: from rest_framework_swagger.views import get_swagger_view schema_view = get_swagger_view(title='API文档') urlpatterns += [ path(r'docs/', sch

  • SpringBoot集成Swagger2构建在线API文档的代码详解

    第一部分:代码集成 pom.xml <!--swagger2配置--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.4.0</version> </dependency> <dependency> <groupId>i

  • spring boot集成smart-doc自动生成接口文档详解

    目录 前言 功能特性 1 项目中创建 /src/main/resources/smart-doc.json配置文件 2 配置内容如下(指定文档的输出路径) 3 pom.xml下添加配置 4 运行插件 5 找到存放路径浏览器打开 6 测试结果 前言 smart-doc 是一款同时支持 java restful api 和 Apache Dubbo rpc 接口文档生成的工具,smart-doc 颠覆了传统类似 swagger 这种大量采用注解侵入来生成文档的实现方法. smart-doc 完全基于

  • 教你怎么用java一键自动生成数据库文档

    这是该工具的github地址:https://github.com/pingfangushi/screw 一.引入pom.xml依赖 <dependencies> <!-- screw 库,简洁好用的数据库表结构文档生成器 --> <dependency> <groupId>cn.smallbun.screw</groupId> <artifactId>screw-core</artifactId> <version

  • 将JavaDoc注释生成API文档的操作

    目录 将JavaDoc 注释 生成API文档 java自动api文档生成Yapi word文档缺点 swwager文档缺点 将JavaDoc 注释 生成API文档 1. 打开java代码,编写JavaDoc 注释,只有按照java的规范编写注释,才能很好的生成API文档,javadoc注释与普通注释的区别为多一个*(星号).普通代码注释为/*XXX*/,而javadoc的注释为/**XXX*/ 2. javadoc注释要尽量写的详细,这样别人在没有源码的情况下才知道如 何使用您的代码. 3. 点

  • Babel自动生成Attribute文档实现详解

    目录 1. 前言 2. 开发自动生成属性文档插件 2.1 生成Babel插件模板: 2.2 转换思路详解: 2.3 单元测试用例: 2.4 AST分析详解: 2.5 插件开发过程: 2.5.1 定义Comment.ApiTable类型对象: 2.5.2 插件主逻辑分析: 2.5.3 主逻辑实现: 2.5.4 注释解析函数: 2.5.5 Markdown表格拼装: 2.5.6生成结果展示~ 3. 总结 1. 前言 利用Babel自动解析源码属性上的注释生成对应Markdown文档,这个场景的应用主

  • eclipse中自动生成javadoc文档的方法

    本文实例讲述了eclipse中自动生成javadoc文档的方法.分享给大家供大家参考.具体方法如下: 使用eclipse生成文档(javadoc)主要有三种方法: 1. 在项目列表中按右键,选择Export(导出),然后在Export(导出)对话框中选择java下的javadoc,提交到下一步. 在Javadoc Generation对话框中有两个地方要注意的: javadoc command:应该选择jdk的bin/javadoc.exe destination:为生成文档的保存路径,可自由选

随机推荐