SpringMVC 添加swagger2自动生成API接口文档

于 2021-04-16 12:14:21 发布
阅读量306 收藏
点赞数
分类专栏： java 文章标签： springmvc swagger2
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/weixin_44152095/article/details/115754392
版权

SpringMVC 添加swagger2自动生成API接口文档

为什么使用Swagger2

我们对Markdown编辑器进行了一些功能拓展与语法支持，除了标准的Markdown编辑器功能，我们增加了如下几点新功能，帮助你用它写博客：

  1. 代码变，文档变 ，只需要少量的注解，Swagger 就可以根据代码自动生成 API 文档，很好的保证了文档的时效性；
  2. 跨语言性，支持 40 多种语言；
  3. Swagger UI 呈现出来的是一份可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程；
  4. 还可以将文档规范导入相关的工具（例如 Postman、SoapUI）, 这些工具将会为我们自动地创建自动化测试；

开发环境准备

  1. JDK:1.8.0_281
  2. Spring:4.1.6.RELEASE
  3. swagger2:2.8.0

1、pom.xml

<properties>
		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
		<spring.version>4.1.6.RELEASE</spring.version>
</properties>
<dependencies>
<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>spring-core</artifactId>
			<version>${spring.version}</version>
		</dependency>
		<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>spring-web</artifactId>
			<version>${spring.version}</version>
		</dependency>
		<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>spring-webmvc</artifactId>
			<version>${spring.version}</version>
		</dependency>
		<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>spring-tx</artifactId>
			<version>${spring.version}</version>
		</dependency>
		<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>spring-context</artifactId>
			<version>${spring.version}</version>
		</dependency>
		<!-- https://mvnrepository.com/artifact/org.springframework/spring-jdbc -->
		<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>spring-jdbc</artifactId>
			<version>${spring.version}</version>
		</dependency>
		<!-- https://mvnrepository.com/artifact/org.springframework/spring-aop -->
		<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>spring-aop</artifactId>
			<version>${spring.version}</version>
		</dependency>
		<!-- swagger2 -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.8.0</version>
		</dependency>
		<!-- https://mvnrepository.com/artifact/io.springfox/springfox-core -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-core</artifactId>
			<version>2.8.0</version>
		</dependency>
		<!-- https://mvnrepository.com/artifact/io.springfox/springfox-schema -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-schema</artifactId>
			<version>2.8.0</version>
		</dependency>

		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.8.0</version>
		</dependency>
		<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/swagger-bootstrap-ui -->
		<dependency>
			<groupId>com.github.xiaoymin</groupId>
			<artifactId>swagger-bootstrap-ui</artifactId>
			<version>1.9.6</version>
		</dependency>

		<dependency>
			<groupId>com.fasterxml.jackson.core</groupId>
			<artifactId>jackson-databind</artifactId>
			<version>2.8.8</version>
		</dependency>
</dependencies>

2、web.xml

<!-- 前端控制器开始 -->
	<servlet>
		<servlet-name>springmvc</servlet-name>
		<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
		<init-param>
			<param-name>contextConfigLocation</param-name>
			<param-value>classpath:springmvc.xml</param-value>
		</init-param>
		<load-on-startup>1</load-on-startup>
	</servlet>
	
	<servlet-mapping>
		<servlet-name>springmvc</servlet-name>
		<url-pattern>/</url-pattern><!--这里很重要-->
	</servlet-mapping>

3、springmvc.xml

<!-- 配置静态文件放行 -->
<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/>
<mvc:resources mapping="doc.html" location="classpath:/META-INF/resources/"/>
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>
<mvc:resources mapping="/swagger/**" location="classpath:/swagger/"/>
<!-- 添加扫描配置类 -->
<bean class="com.ly.toucher.config.SwaggerConfig" />

4、application-service.xml

<context:component-scan base-package="com.ly"></context:component-scan>

5、新建SwaggerConfig配置类

package com.ly.toucher.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableWebMvc
@EnableSwagger2
@ComponentScan(basePackages ="com.ly")
public class SwaggerConfig{

	@Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
        		.apiInfo(apiInfo())
//        		.groupName("用户相关接口")
        		.select()
//              .apis(RequestHandlerSelectors.basePackage("com.ly.toucher.controller"))//为当前配置的包下controller生成API文档
//        		.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))//为有@Api注解的Controller生成API文档
//        		.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))//为有@ApiOperation注解的方法生成API文档
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("APIs")
            .description("快速上手,快速开发,快速交接")
            .contact(new Contact("接口文档", "http://localhost:8080/Radar/swagger-ui.html", ""))
            .version("1.0.0")
            .build();
    }
}

6、@Controller测试

@ApiOperation(nickname = "swagger-helloworld", value = "Swagger的世界", notes = "测试HelloWorld")
	@ApiImplicitParam(name="nickname",value="昵称",required=true,paramType="query",dataType="String")
	@RequestMapping(value = "/helloworld", method = RequestMethod.GET)
    public String helloWorld(@RequestParam String nickname) {  //@ApiParam(value = "昵称") 
       System.out.println("helloWorld"+nickname);
       return "helloWorld"+nickname;
    }

Swagger2注解详解

1、@Api ：请求类的说明

@Api：放在请求的类上，与 @Controller 并列，说明类的作用，如用户模块，订单类等。
    tags="说明该类的作用"
    value="该参数没什么意义，所以不需要配置"

@Api(tags = "账户相关模块")
@RestController
@RequestMapping("/account")
public class AccountController {
    //业务类
}

2、@ApiOperation：方法的说明

@ApiOperation："用在请求的方法上，说明方法的作用"
    value="说明方法的作用"
    notes="方法的备注说明"

@ApiOperation(value = "修改密码", notes = "方法的备注说明，如果有可以写在这里")
@PostMapping("/changepass")
public AjaxResult changePassword(@AutosetParam SessionInfo sessionInfo,@RequestBody @Valid PasswordModel passwordModel) {
    //业务类
}

3、@ApiImplicitParams、@ApiImplicitParam：方法参数的说明

@ApiImplicitParams：用在请求的方法上，包含一组参数说明
    @ApiImplicitParam：对单个参数的说明      
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（请求体）-->  @RequestBody User user
            · form（普通表单提交）     
        dataType：参数类型，默认String，其它值dataType="int"       
        defaultValue：参数的默认值

@ApiOperation(value="用户登录",notes="随边说点啥")
@ApiImplicitParams({
        @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
        @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
        @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
})
@PostMapping("/login")
public AjaxResult login(@RequestParam String mobile, @RequestParam String password, @RequestParam Integer age){
    //业务类
    return AjaxResult.OK();
}

@ApiOperation("根据部门Id删除")
@ApiImplicitParam(name="depId",value="部门id",required=true,paramType="query")
@GetMapping("/delete")
public AjaxResult delete(String depId) {
    //TODO
}

4、@ApiResponses、@ApiResponse：方法返回值的说明

@ApiResponses：方法返回对象的说明
    @ApiResponse：每个参数的说明
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

@ApiOperation(value = "修改密码", notes = "方法的备注说明")
@ApiResponses({
        @ApiResponse(code = 400, message = "请求参数异常"),
        @ApiResponse(code = 404, message = "请求路径异常")
})
@PostMapping("/changepass")
public AjaxResult changePassword(@AutosetParam SessionInfo sessionInfo, @RequestBody @Valid PasswordModel passwordModel) {
    //业务类
}

5、@ApiModel：用于JavaBean上面，表示一个JavaBean

@ApiModel：用于JavaBean的类上面，表示此 JavaBean 整体的信息（这种一般用在post创建的时候，使用 @RequestBody 这样的场景，请求参数无法使用 @ApiImplicitParam 注解进行描述的时候 ）

6. @ApiModelProperty：用在JavaBean的属性上面，说明属性的含义

@ApiModel("修改密码所需参数封装类")
public class PasswordModel
{
    @ApiModelProperty("账户Id")
    private String accountId;
//TODO
}

两种风格展示

1、swagger-ui

jar:swagger-ui

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

地址：http://localhost:8080/项目明 /swagger-ui.html
在这里插入图片描述

2、swagger-bootstrap-ui

jar：swagger-bootstrap-ui

<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>swagger-bootstrap-ui</artifactId>
	<version>1.9.6</version>
</dependency>

地址：http://localhost:8080/项目明 /doc.html
在这里插入图片描述

3、其他风格

jar:swagger-ui-layer

<dependency>
	<groupId>com.github.caspar-chen</groupId>
	<artifactId>swagger-ui-layer</artifactId>
	<version>1.1.3</version>
</dependency>

地址：http://localhost:8080/项目明 /docs.html
在这里插入图片描述

KingLJade
关注
  • 0
    点赞
  • 踩
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
专栏目录
SpringMVC 集成 Swagger2
06-01
SpringMVC 集成Swagger2，相关说明可以打开 https://blog.csdn.net/everyday_hzg/article/details/80537902
c#配置swagger文档
qq_53217825的博客
05-16 4655
虽然现在已经有.net8.0了，但是.net6因为已经出来两年了，所以更多公司在用，而且6.0和8.0的差别并不是很大，还是有一些可学的地方的，目前.net core 6.0的资料是最多的，所以搭建项目建议使用6.0会比较好。和上一个基本一致，注释都在代码中有写，在项目属性中开启“生成包含api文档的文件”，开启方法》右键项目》属性》生成》输出》打开“生成包含api的文档的文件”我们的项目地址应该在这里设置，其中以什么方式运行，这个就是基础了，试一下就知道了，勾选openapi支持。
springmvc集成swagger实现接口文档自动化生成
liufei198613的博客
07-01 1万+
一直苦于文档整理工作，因为这是一个很无聊的工作，偶然在网上看到了swagger这东西，感觉不错，于是动手集成了一下，眼前一亮           Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagge
Spring MVC中使用Swagger生成API文档和完整项目示例Demo，swagger-server-api
weixin_30535565的博客
07-16 246
本文作者：小雷FansUnion-一个有创业和投资经验的资深程序员-全球最大中文IT社区CSDN知名博主-排名第119 实际项目中非常需要写文档，提高Java服务端和Web前端以及移动端的对接效率。 听说Swagger这个工具，还不错，就网上找了些资料，自己实践了下。一：Swagger介绍Swagger是当前最好用的Restful API文档生成的开源项目，通过swagger-spring...
Spring MVC+Swagger2
qq_27127145的博客
12-17 255
本文主要介绍在Spring MVC上搭建Swagger，方便生成API文档及调试 第一步：在maven中引入依赖 &lt;!--swagger--&gt; &lt;dependency&gt; &lt;groupId&gt;io.springfox&lt;/groupId&gt; &lt;artifactId&gt;springfox-swagger-ui&lt;/artifac...
Swagger与SpringMvc集成生成Restful形式接口文档
热门推荐
zjx2016的博客
06-29 2万+
swagger提供的接口文档相比传统的文档方式更加直观也更加高效，但是在网上找了很多关于Swagger与SpringMvc整合的资料，发现都比较繁琐，不是很满意，于是有了这篇博客，希望对大家有所帮助。
swagger整合SpringMvc生成Restful api
07-05
swagger提供的接口文档相比传统的文档方式更加直观也更加高效，但是在网上找了很多关于Swagger与SpringMvc整合的资料，发现都比较繁琐，不是很满意，于是有了这篇博客，希望对大家有所帮助。教程：...
SpringMVC+SwaggerUI
12-04
SpringMVC+Swagger UI生成可视图的API文档的demo
swagger-maven-plugin:支持JAX-RS和SpringMVC的maven构建插件，可帮助您在构建阶段生成Swagger JSON和API文档
04-30
Swagger Maven插件 这个插件使您的Swagger注释项目可以在maven构建阶段生成Swagger规范和可自定义的模板化静态文档。 与swagger-core不同，swagger-maven-plugin不会在其余应用程序中主动满足规范要求。 它将规范...
swagger集成springMVC简单示例
10-28
Spring MVC中使用Swagger生成API文档和完整项目示例Demo
springmvc api chm 文档
10-30
springmvc api chm 文档,3.0版本springmvc api chm 文档,3.0版本
spring-webmvc-5.3.15-API文档-中文版.zip
05-07
赠送jar包：spring-webmvc-5.3.15.jar； 赠送原API文档：spring-webmvc-5.3.15-javadoc.jar； 赠送源代码：spring-webmvc-5.3.15-sources.jar； 赠送Maven依赖信息文件：spring-webmvc-5.3.15.pom； 包含翻译后的API文档：spring-webmvc-5.3.15-javadoc-API文档-中文(简体)版.zip； Maven坐标：org.springframework:spring-webmvc:5.3.15； 标签：spring、webmvc、springframework、jar包、java、中文文档； 使用方法：解压翻译后的API文档，用浏览器打开“index.html”文件，即可纵览文档内容。 人性化翻译，文档中的代码和结构保持不变，注释和说明精准翻译，请放心使用。
SpringMvc整合swagger2 .docx下载
02-24
在ibase4j项目的学习中得知了swagger在线文档的存在，在网上参考了许多资源才实现了不需要下载swagger-ui放在webapp目录下就能实现在线api文档测试功能。分享给大家，少走弯路。
swagger2 整合springmvc
11-23
swagger2整合springmvc最简单的配置 直接解压导入myeclipse, 部署运行，http://localhost:8080/Hi/swagger/index.html 可看效果。
server-api:SERVER-API 是一个gui的web接口管理工具，基于 swagger-ui 的后台API开源项目，采用SpringMvc+Maven3+Jdk1.7+Tomcat7
05-23
满足日益增长的接口文档需求，这里包括（接口文档的格式，权限，视图，Mock数据，Api监控,自动化测试,接口文档分享，版本管理等），server-api 可以帮助后台开发人员解放双手，直接用注解生成文档，省去与前端、测试...
SpringMVC集成Swagger2详解
wujiumengxing的博客
03-20 406
随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架。Swagger能成为最受欢迎的REST APIs文档生成工具之一，有以下几个原因：    Swagger ...
Spring MVC 集成 Swagger2
不务正业的野猴子
07-07 168
一、添加Swagger2依赖 在spring-mybatis-sample-web模块的pom.xml文件中添加如下依赖: <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <v...
SpringMvc 集成swagger2
zhangjun19900306的博客
04-25 1936
本人刚接触到swagger2，如有什么不足的地方，希望大神帮我指出，谢谢
springmvc 自动生成接口文档
最新发布
12-28
Spring MVC提供了一种自动生成接口文档的方式，可以通过注解来实现。以下是一个示例： ```java @RestController @RequestMapping("/api") public class UserController { @ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户信息") @ApiImplicitParam(name = "userId", value = "用户ID", required = true, dataType = "Long", paramType = "path") @GetMapping("/users/{userId}") public User getUser(@PathVariable Long userId) { // 根据用户ID查询用户信息 // ... } @ApiOperation(value = "创建用户", notes = "根据传入的用户信息创建用户") @ApiImplicitParam(name = "user", value = "用户信息", required = true, dataType = "User", paramType = "body") @PostMapping("/users") public User createUser(@RequestBody User user) { // 创建用户 // ... } // 其他接口... } ``` 在上面的示例中，我们使用了`@ApiOperation`注解来描述接口的功能和说明，使用`@ApiImplicitParam`注解来描述接口的参数信息。这些注解可以帮助生成接口文档，并提供给前端、测试等人员查看和使用。 需要注意的是，为了能够自动生成接口文档，你需要在项目中引入相应的依赖，例如`springfox-swagger2`和`springfox-swagger-ui`。具体的配置和使用方法可以参考Springfox Swagger的官方文档。

“相关推荐”对你有帮助么？

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

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

抵扣说明：

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

余额充值