spring boot ＋Swagger-ui 自动生成API文档(转)

最新推荐文章于 2024-07-06 14:24:13 发布
最新推荐文章于 2024-07-06 14:24:13 发布
阅读量1.5k 收藏 3
点赞数
分类专栏： 架构

spring boot ＋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>
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19

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();
    }
}
  • 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

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);
    }
}
  • 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
  • 73
  • 74
  • 75
  • 76
  • 77
  • 78
  • 79
  • 80
  • 81
  • 82
  • 83
  • 84
  • 85
  • 86
  • 87
  • 88
  • 89
  • 90
  • 91
  • 92
  • 93
  • 94
  • 95
  • 96
  • 97
  • 98
  • 99
  • 100
  • 101
  • 102
  • 103
  • 104
  • 105
  • 106
  • 107
  • 108
  • 109
  • 110
  • 111
  • 112
  • 113
  • 114
  • 115
  • 116
  • 117
  • 118
  • 119
  • 120
  • 121
  • 122
  • 123
  • 124
  • 125
  • 126
  • 127
  • 128
  • 129
  • 130
  • 131

注解含义：

@Api：用在类上，说明该类的作用。

@ApiOperation：注解来给API增加方法说明。

@ApiImplicitParams : 用在方法上包含一组参数说明。

@ApiImplicitParam：用来注解来给方法入参增加说明。

@ApiResponses：用于表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

      code：数字，例如400

      message：信息，例如"请求参数没填好"

      response：抛出异常的类   

@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：描述一个model的属性
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20

注意：@ApiImplicitParam的参数说明： 
这里写图片描述

paramType会直接影响程序的运行期，如果paramType与方法参数获取使用的注解不一致，会直接影响到参数的接收。

4、启动项目效果图：

服务器启动后访问 http://localhost:8099/swagger-ui.html 效果如下 
这里写图片描述
点击查看效果 
这里写图片描述

本文项目全部代码：https://github.com/527515025/springBoot/tree/master/springboot-swagger-ui

本文参考：https://blog.csdn.net/machihaoyu/article/details/78475699 
https://blog.csdn.net/tuposky/article/details/77965139 
https://blog.csdn.net/sanyaoxu_2/article/details/80555328

rainyear
关注
  • 0
    点赞
  • 踩
  • 3
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
专栏目录
【开源】Springboot API 一键生成器
weixin_47083537的博客
10-13 538
Springboot API 一键生成器 写这个项目，最大的想法就是：不做CRUD 程序猿 Springboot 在我们平时开发项目当中，是如此的常用。然而，比如平时我们写的一些： XX 管理系统 XX 管理后台 XX XXXX 诸如此类，无非是一张表格、带有分页、非常标准的一个增删改查 页面。很多时候再想，这样重复的工作，能不能有一个东西替我们实现呢？把重复的代码生成，而我关注有 业务逻辑 的地方就行。 欢迎Star，你的支持是我继续的动力！ 生成代码示例 首先、你肯定
使用swagger自动生成Api文档
爱死亡机器人
12-18 168
https://razeencheng.com/post/go-swagger https://blog.csdn.net/zhanggonglalala/article/details/98070986
Spring Boot中的API文档生成
最新发布
微赚淘客开发者博客
07-06 849
API文档不仅提供了对外部开发人员使用你的API的指导，还在团队内部提供了清晰的接口定义和使用说明。Spring Boot作为一个流行的Java开发框架，提供了多种方式来生成和管理API文档，本文将介绍其中的一些方法和最佳实践。Swagger是一个流行的API文档生成工具，它可以自动化地从Spring Boot应用程序中的代码生成API文档，并提供一个交互式的UI界面来测试API。通过本文，我们详细介绍了在Spring Boot中使用Swagger生成API文档的方法，并探讨了其他一些选择。
Spring Boot 2整合Knife4j自动生成API文档
m0_74205854的博客
04-24 427
springboot3进行使用Knife4j的教程,但是在实际的开发中,还是有很多的项目使用的是springboot2使用Knife4j,所以这期进行介绍springboot2如何的进行整合Knife4j.
SpringBoot结合Swagger2自动生成api文档的方法
08-26
主要介绍了SpringBoot结合Swagger2自动生成api文档的方法，小编觉得挺不错的，现在分享给大家，也给大家做个参考。一起跟随小编过来看看吧
Swagger导出接口文档（简单版）
weixin_52270065的博客
04-29 1198
之后运行项目访问http://localhost:项目端口号/swagger-ui.html。可以任选则以上的框复制里边的json数据，然后打开网站。，将json数据粘贴生成即可。
SpringBoot＋Swagger-ui自动生成API文档
08-26
这两个依赖分别用于核心的API文档生成和用户界面的展示。 ```xml <groupId>io.springfox <artifactId>springfox-swagger2 <version>2.2.2 <groupId>io.springfox <artifactId>springfox-swagger-ui ...
Spring Boot引入swagger-ui 后swagger-ui.html无法访问404的问题
09-07
除此之外，为了使前端更好地利用Swagger生成的API文档，可以考虑使用前端库（如Vue.js的typescript版本）来自动化生成调用API的代码。例如，可以参考文章中提到的开源npm库，以便前端使用axios更方便地调用API。 ...
spring boot 2整合swagger-ui过程解析
08-25
Spring Boot 2 整合 Swagger UI 是为了提供一个交互式的文档系统，帮助开发者轻松地测试和理解API接口。Swagger UI 是基于 Swagger 的一个用户界面，它允许用户通过浏览器直接查看、测试和操作API。以下是对整合过程...
在Spring Boot中使用swagger-bootstrap-ui的方法
08-28
swagger是一个流行的API文档生成工具，能够自动生成API文档。swagger-bootstrap-ui是基于swagger的UI组件，提供了更加友好的界面和交互方式。在Spring Boot中使用swagger-bootstrap-ui可以提供一个更加友好的API文档...
spring-boot-swagger-ui:Spring Boot Swagger UI
07-04
Spring Boot Swagger UI 是一个基于Java开发的Web应用，它整合了Swagger工具，使得在Spring Boot项目中能够方便地实现API接口的文档化和测试。Swagger UI是一个用户界面，用于展示和交互Swagger规范定义的RESTful ...
spring-boot，swagger2，生成html及中文pdf示例
04-24
spring-boot，swagger2，生成html及中文pdf示例。 https://download.csdn.net/download/lihuaijun/10313631 asciidoctorj-pdf支持中文生成 这个资源的评论里，有人说运行出错，我把例子发上来
swagger ui API文档工具
04-08
随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。 前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架
swagger导出静态API文档工具
08-29
工具是一个maven工程，可通过maven命令导出静态接口文档,具体操作步骤见附件中的ReadMe.txt
项目API文档在线自动生成 Swagger UI.zip
07-19
Swagger UI是一款RESTFUL接口的文档在线自动生成 功能测试功能软件。       现在多数的项目开发中，网站和移动端都需要进行数据交互和对接，这少不了使用REST编写API接口这种场景。例如有些团队，移动端交由了另一团队开发，不同开发小组之间就需要以规范和文档作为标准和协作基础。良好的文档可以让开发事半功倍，而作为又懒又要效率又能交代的码农，当然最希望一 切自动化，或用小聪明来找到最适合的工具。       Swagger-UI简单而一目了然。它能够纯碎的基于html javascript实现，只要稍微整合一下便能成为方便的API在线测试工具。       项目的设计架构中一直提倡使用TDD（测试驱动）原则来开发，swagger-ui在这方面更是能提供很大帮助。 Swagger-UI更倾向于在线测试接口和数据，但其核心是一个javascript插件，只要稍作修改，便能按需求定制出不同格式的说明文档，在github上更是基于它集成到各种语言环境，分支众多。        其官方提供了一个离线版本，它的使用方法十分简单：直接在js格式的资源文件中录入REST API的json信息，便能容易地生成不同模块下的API列表，每个API接口描述和参数、请求方法都能在每个json数组中定制。下面是目前项目中使用到的部分预览图：  Swagger-UI 的官方地址： http://swagger.wordnik.com Github上的项目地址： https://github.com/wordnik/swagger-ui 官方提供的demo地址 http://petstore.swagger.wordnik.com/ 标签：api
不下载任何插件和依赖，在线导出swagger的api接口文档（word）
2301_78149288的博客
02-02 8392
不需要任何依赖和插件，swagger生成的api文档开始导出word
Swagger2使用及导出api文档
yanzanjie2018的博客
05-10 4574
swagger2依赖、导出接口文档 <!--Swagger-UI API文档生产工具--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version>
swagger-ui接口文档转换为html或word格式
qq_45445841的博客
03-11 2268
swagger-ui接口文档转换为html或word格式创建3个实体类+1个html获取Json数据解析JSON数据controller文件创建接口，启动查看结果 swagger-ui生成的接口文档想来大家用者不少，但是有时候需要打印或者各种需求，那么怎么转换成html或者word格式呢，下面带大家一起看一下（代码可直接复制使用，部分已标注地方需根据各自项目进行修改）。 创建3个实体类+1个htm...
Web菜鸟入门教程 - Swagger实现自动生成文档
zhonglunshun的专栏
08-14 1351
如果是一个人把啥都开发了，那用不到Swagger-UI，但一般情况是前后端分离的，所以就需要告诉前端开发人员都有哪些接口，传入什么参数，怎么调用，返回什么。有了Swagger-UI就能把这部分文档编写的业务给省去了。Swagger-UI是HTML, Javascript, CSS的一个集合，可以动态地根据注解生成在线API文档。
Spring Boot快速集成Swagger2生成API文档及其依赖升级
这个starter项目提供了一个易于使用的API文档生成框架，通过Spring Boot的自动配置，开发者可以在不编写额外代码的情况下，轻松地为Spring Boot应用添加Swagger支持。它能够自动生成基于注解的API文档，使得API的...
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值