springboot项目集成swagger并导出成文档

EricFRQ

已于 2023-12-13 14:01:38 修改

阅读量1.9k

点赞数

分类专栏： springboot项目相关文章标签： spring boot

于 2020-11-16 17:58:13 首次发布

本文链接：https://blog.csdn.net/weixin_42707397/article/details/109726239

版权

springboot项目相关专栏收录该内容

43 篇文章 3 订阅

订阅专栏

springboot项目集成swagger并导出成文档

一、集成swagger
二、导出成文档

一、集成swagger

1、加入依赖

<!-- swagger2.x -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
或者
<!-- swagger3.x -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.1.0</version>
</dependency>

2、启动入口类加注解

@EnableSwagger2
@EnableAutoConfiguration

修改swagger相关配置，按需修改即可，使用默认配置就不必修改

# /api-docs endpoint custom path 默认 /v3/api-docs
springdoc.api-docs.path=/api-docs

# swagger 相关配置在  springdoc.swagger-ui
# swagger-ui custom path
springdoc.swagger-ui.path=/swagger-ui.html

springdoc.show-actuator=true

3、配置类config包下

swagger2.x的写法

package com.xxx.xxx.config;

import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author furenqiang
 */

//swagger2的配置文件，在项目的启动类的同级文件建立
@Configuration
@EnableSwagger2
//是否开启swagger，正式环境一般是需要关闭的（避免不必要的漏洞暴露！），可根据springboot的多环境配置进行设置
@ConditionalOnProperty(name = "swagger.enable", havingValue = "true")
public class SwaggerConfig {
	// swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
				// 为当前包路径
				.apis(RequestHandlerSelectors.basePackage("com.northpool.stockDataOper.dataModel.controller"))
				.paths(PathSelectors.any()).build();
	}

	// 构建 api文档的详细信息函数,注意这里的注解引用的是哪个
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				// 页面标题
				.title("Spring Boot 测试使用 Swagger2 构建RESTful API")
				// 创建人信息
				.contact(new Contact("furenqiang", "", ""))
				// 版本号
				.version("1.0")
				// 描述
				.description("API 描述").build();
	}
}

swagger3.x的写法:
这段代码是一个Spring Boot应用中配置Swagger分组和整体描述的示例。代码中使用了注解@Bean声明了两个方法publicApi()和adminApi()来定义不同路径的接口分组。方法publicApi()将路径以/public/**匹配到组名为"springshop-public"的分组中，方法adminApi()将路径以/admin/**匹配到组名为"springshop-admin"的分组中，并且使用了方法过滤器method -> method.isAnnotationPresent(Admin.class)来过滤只有@Admin注解的方法。另外还定义了一个springShopOpenAPI()方法来配置整体描述。

//将不同路径的接口分组，比如/public在springshop-public组里，在swagger页面的右上角可以切换分组
 @Bean
  public GroupedOpenApi publicApi() {
      return GroupedOpenApi.builder()
              .group("springshop-public")
              .pathsToMatch("/public/**")
              .build();
  }
  @Bean
  public GroupedOpenApi adminApi() {
      return GroupedOpenApi.builder()
              .group("springshop-admin")
              .pathsToMatch("/admin/**")
              .addMethodFilter(method -> method.isAnnotationPresent(Admin.class))
              .build();
  }
  
  //配置左上角对文档的整体描述
  @Bean
  public OpenAPI springShopOpenAPI() {
      return new OpenAPI()
              .info(new Info().title("SpringShop API")
              .description("Spring shop sample application")
              .version("v0.0.1")
              .license(new License().name("Apache 2.0").url("http://springdoc.org")))
              .externalDocs(new ExternalDocumentation()
              .description("SpringShop Wiki Documentation")
              .url("https://springshop.wiki.github.org/docs"));
  }

4、控制器使用swagger

package com.northpool.stockDataOper.dataModel.controller;

import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.UUID;
import java.util.zip.ZipOutputStream;

import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import org.apache.commons.io.FileUtils;
import org.apache.commons.lang3.StringUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.multipart.MultipartFile;

import com.northpool.stockDataOper.base.result.Result;
import com.northpool.stockDataOper.base.util.IOtools;
import com.northpool.stockDataOper.base.valid.UpdateAction;
import com.northpool.stockDataOper.dataModel.datamodelresolve.DataModel;
import com.northpool.stockDataOper.dataModel.model.TbStockDataModel;
import com.northpool.stockDataOper.dataModel.service.DataModelService;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;

@Slf4j
@RestController
@RequestMapping("/stock/model")
@Api("模型相关的api")
public class ModelController {

	@Autowired
	DataModelService dataModelService;

	/**
	 * 数据模型获取目录树
	 * 
	 * @param rootId
	 * @return
	 * @throws IOException
	 */
	@ApiOperation(value = "获取模型树", httpMethod = "GET")
	@ApiImplicitParams({ @ApiImplicitParam(name = "rootId", value = "根id", dataType = "String") })
	@ResponseBody
	@RequestMapping(value = "/getDataModelTree", method = { RequestMethod.GET, RequestMethod.POST })
	public Result getDataModelTree(@RequestParam(required = false, defaultValue = "-1") String rootId,
			HttpServletRequest request) throws IOException {
		// SessionUtil.getUserId(request);

		Result result = new Result();
		try {
			return dataModelService.getDataModelTree(rootId);
		} catch (Exception e) {
			log.error(e.getMessage(), e);
			return result.setError("error", "查询出错");
		}
	}
 }
 
 /**
	 * 根据id获取元数据
	 * 
	 * @param
	 * @return
	 * @author Eric
	 * @Time 2020年10月13日
	 */
	@ApiOperation(value = "根据id获取元数据", httpMethod = "GET")
	@ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "节点ID", dataType = "String"),
			@ApiImplicitParam(name = "type", value = "节点类型, 1-数据库 2-表格 3-文件夹 4-文件", dataType = "Integer"),
			@ApiImplicitParam(name = "name", value = "表名称，节点类型为2时必传", dataType = "String") })
	@ResponseBody
	@RequestMapping(value = "/getMetaDataByParams", method = { RequestMethod.GET, RequestMethod.POST })
	public Result<Object> getMetaDataByParams(HttpServletRequest request, MetaData metaData) {
		try {
			return dataResourceService.getMetaDataByParams(metaData);
		} catch (Exception e) {
			log.error(e.getMessage(), e);
			return new Result<Object>("error", "查询出错");
		}
	}
}

二、导出成文档

导出文档前提：上面集成swagger成功后访问http://localhost:8084/v2/api-docs，可看到如下图
在这里插入图片描述

1、pom添加依赖

 <!-- swagger生成文档依赖 -->
		<dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.1</version>
        </dependency>

2、pom添加插件

 <!--swagger接口导出与 打包为markup 插件 使用方式： 0，确认系统的 /v2/api-docs 接口可用 1，修改configuration.swaggerInput 
				标签内容，将源地址：http://127.0.0.1:8594/product/v2/api-docs 修改为当前项目可0可访问路径； 2，运行当前项目 
				； 3，进入项目根目录，执行mvn命令：mvn swagger2markup:convertSwagger2markup -->
			<plugin>
				<groupId>io.github.swagger2markup</groupId>
				<artifactId>swagger2markup-maven-plugin</artifactId>
				<version>1.3.1</version>
				<configuration>
					<!-- api-docs访问url -->
					<swaggerInput>http://localhost:8084/v2/api-docs</swaggerInput>
					<!-- 生成为单个文档，输出路径 
					<outputFile>src/main/doc/api</outputFile>-->
					<!-- 生成为多个文档，输出路径 -->
					<outputDir>src/docs/asciidoc/generated</outputDir>
					<config>
						<!-- wiki格式文档 -->
						<!--<swagger2markup.markupLanguage>CONFLUENCE_MARKUP</swagger2markup.markupLanguage> -->
						<!-- ascii格式文档 -->
						<swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
						<!-- markdown格式文档 -->
						<!--<swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage>-->
						<swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
					</config>
				</configuration>
			</plugin>
			<!--此插件生成HTML和PDF-->
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.3</version>
                <!-- Include Asciidoctor PDF for pdf generation -->
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <version>1.5.0-alpha.10.1</version>
                    </dependency>
                    <dependency>
                        <groupId>org.jruby</groupId>
                        <artifactId>jruby-complete</artifactId>
                        <version>1.7.21</version>
                    </dependency>
                </dependencies>
                <!-- Configure generic document generation settings -->
                <configuration>
                    <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
                    <sourceHighlighter>coderay</sourceHighlighter>
                    <attributes>
                        <toc>left</toc>
                    </attributes>
                </configuration>
                <!-- Since each execution can only handle one backend, run
                     separate executions for each desired output type -->
                <executions>
                    <execution>
                        <id>output-html</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>html5</backend>
                            <outputDirectory>src/docs/asciidoc/html</outputDirectory>
                        </configuration>
                    </execution>
 
                    <execution>
                        <id>output-pdf</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>pdf</backend>
                            <outputDirectory>src/docs/asciidoc/pdf</outputDirectory>
                        </configuration>
                    </execution>
 
                </executions>
            </plugin>

注意，将

<swaggerInput>http://localhost:8084/v2/api-docs</swaggerInput>

改为自己的地址

3、进入项目根目录，依次运行下面两个命令

1. mvn swagger2markup:convertSwagger2markup 
2. mvn generate-resources

运行结果都是：build success
如果报路径\src\docs\asciidoc\generated没找到，就手动创建一个generated的文件夹
导出成功后如下：
在这里插入图片描述

4、补充其他方法（还未测试是否可行）：

Swagger生成离线PDF、HTML、WORD、MARKDOWN（全网最简版本）

EricFRQ

关注

0
点赞
踩
4

收藏

觉得还不错? 一键收藏
0
评论
springboot项目集成swagger并导出成文档

一、加入依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency&gt
复制链接

扫一扫