springboot+maven/gradle整合swag及生成静态文档

最新推荐文章于 2024-05-13 10:17:24 发布
最新推荐文章于 2024-05-13 10:17:24 发布
阅读量411 收藏 1
点赞数
文章标签： spring boot
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/weixin_44124385/article/details/106407537
版权

springboot整合swag及生成静态文档

完整git地址

maven项目

链接: https://github.com/fjlcyl/springboot-swagger.git.

gradle项目

链接: https://github.com/fjlcyl/springboot-swagger-gradle.git.

pom文件如下

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.3.0.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.example</groupId>
    <artifactId>swagger-test</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>swagger-test</name>
    <description>Demo project for Spring Boot</description>

    <properties>
        <java.version>1.8</java.version>
    </properties>

    <dependencies>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
            <exclusions>
                <exclusion>
                    <groupId>org.junit.vintage</groupId>
                    <artifactId>junit-vintage-engine</artifactId>
                </exclusion>
            </exclusions>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.12</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.0</version>
        </dependency>
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.1</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-core</artifactId>
            <version>1.5.16</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.16</version>
        </dependency>
    </dependencies>
    <repositories>
        <repository>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
            <id>jcenter-releases</id>
            <name>jcenter</name>
            <url>http://jcenter.bintray.com</url>
        </repository>
    </repositories>
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

如果版本不一致，在导出静态文件时可能会报如下错误：
在这里插入图片描述

1.springboot整合swagger生成在线api

参考: 方志朋的博客.

1.1 目录结构

在这里插入图片描述

1.2 pom文件

   <!--springboot起步依赖-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
            <exclusions>
                <exclusion>
                    <groupId>org.junit.vintage</groupId>
                    <artifactId>junit-vintage-engine</artifactId>
                </exclusion>
            </exclusions>
        </dependency>

   <!--lombok依赖-->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.12</version>
        </dependency>

        <!--swag所需依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.0</version>
        </dependency>

SwaggerConfig配置类

/**
 * 通过createRestApi函数创建Docket的Bean之后，
 * apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）
 * select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，
 * apis()函数扫描所有Controller中定义的API， 并产生文档内容（除了被@ApiIgnore指定的请求）
 * @return
 */

@Configuration//交给spring管理
@EnableSwagger2//swag配置类的初始化
public class SwaggerConfig {
 
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否开启 (true 开启  false隐藏。生产环境建议隐藏)
                .enable(true)
                .select()
                //扫描的路径包,设置basePackage会将包下的所有被@Api标记类的所有方法作为api
                .apis(RequestHandlerSelectors.basePackage("com"))
                //指定路径处理PathSelectors.any()代表所有的路径
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                //设置文档标题(API名称)
                .title("SpringBoot中使用Swagger2构建RESTful接口")
                //文档描述
                .description("接口说明")
                //服务条款URL
                .termsOfServiceUrl("http://127.0.0.1:8080/")
                //联系信息
                .contact("码农新锐")
                //版本号
                .version("1.0。0")
                .build();
    }
}

BookController

package com.example.swaggertest.controller;



import com.example.swaggertest.pojo.Book;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.ui.ModelMap;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

import java.util.*;


@RestController
@RequestMapping(value = "/books")
public class BookController {

    Map<Long, Book> books = Collections.synchronizedMap(new HashMap<Long, Book>());

    @ApiOperation(value="获取图书列表", notes="获取图书列表")
    @RequestMapping(value={""}, method= RequestMethod.GET)
    public List<Book> getBook() {
        List<Book> book = new ArrayList<>();
        for (int i=0;i<5;i++){
            book.add(new Book(1L,"追风筝的人",52f));
        }
        return book;
    }

    @ApiOperation(value="创建图书", notes="创建图书")
    @ApiImplicitParam(name = "book", value = "图书详细实体", required = true, dataType = "Book")
    @RequestMapping(value="", method=RequestMethod.POST)
    public String postBook(@RequestBody Book book) {
        books.put(book.getId(), book);
        return "success";
    }
    @ApiOperation(value="获图书细信息", notes="根据url的id来获取详细信息")
    @ApiImplicitParam(name = "id", value = "ID", required = true, dataType = "Long",paramType = "path")
    @RequestMapping(value="/{id}", method=RequestMethod.GET)
    public Book getBook(@PathVariable Long id) {
        List<Book> book = new ArrayList<>();
        for (int i=0;i<5;i++){
            book.add(new Book((long) i,"追风筝的人",52f));
        }
        for (Book book1 : book) {
            if (book1.getId()==id){
                return book1;
            }

        }
        return new Book(null,"不存在该图书",null);
    }

    @ApiOperation(value="更新信息", notes="根据url的id来指定更新图书信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "图书ID", required = true, dataType = "Long",paramType = "path"),
            @ApiImplicitParam(name = "book", value = "图书实体book", required = true, dataType = "Book")
    })
    @RequestMapping(value="/{id}", method= RequestMethod.PUT)
    public String putUser(@PathVariable Long id, @RequestBody Book book) {
        Book book1 = books.get(id);
        book1.setName(book.getName());
        book1.setPrice(book.getPrice());
        books.put(id, book1);
        return "success";
    }
    @ApiOperation(value="删除图书", notes="根据url的id来指定删除图书")
    @ApiImplicitParam(name = "id", value = "图书ID", required = true, dataType = "Long",paramType = "path")
    @RequestMapping(value="/{id}", method=RequestMethod.DELETE)
    public String deleteUser(@PathVariable Long id) {
        books.remove(id);
        return "success";
    }

    @ApiIgnore//使用该注解忽略这个API
    @RequestMapping(value = "/hi", method = RequestMethod.GET)
    public String  jsonTest() {
        return " hi you!";
    }
}

Book.java

package com.example.swaggertest.pojo;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.experimental.Accessors;

@Data
@NoArgsConstructor
@AllArgsConstructor
@Accessors
public class Book {
    private Long id;
    private String name;
    private Float price;
}

1.3 启动项目

链接: http://localhost:8080/swagger-ui.html.项目的端口
结果如下：
在这里插入图片描述

2 生成静态文档

2.1 pom文件

 <!--swag生成静态文档所需jar包-->
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.1</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-core</artifactId>
            <version>1.5.16</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.16</version>
        </dependency>

pom中还要添加一下远程仓库 （要不要都无所谓）

 <repositories>
        <repository>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
            <id>jcenter-releases</id>
            <name>jcenter</name>
            <url>http://jcenter.bintray.com</url>
        </repository>
    </repositories>

2.1 编写测试类

参考https://blog.csdn.net/qq_34727675/article/details/82961995

@SpringBootTest
public class Swag {
    /**
     * 生成AsciiDocs格式文档
     *
     * @throws Exception
     */
    @Test
    public void generateAsciiDocs() throws Exception {
        //    输出Ascii格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)//设置生成格式
                .withOutputLanguage(Language.ZH)//设置语言中文还是其他语言
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();
        //设置swagger-api的json来源
        Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("./docs/asciidoc/generated"));//设置生成文件的路径
    }

    /**
     * 生成Markdown格式文档
     *
     * @throws Exception
     */
    @Test
    public void generateMarkdownDocs() throws Exception {
        //    输出Markdown格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("./docs/markdown/generated"));
    }

    /**
     * 生成Confluence格式文档
     *
     * @throws Exception
     */
    @Test
    public void generateConfluenceDocs() throws Exception {
        //    输出Confluence使用的格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("./docs/confluence/generated"));
    }

    /**
     * 生成AsciiDocs格式文档,并汇总成一个文件
     *
     * @throws Exception
     */
    @Test
    public void generateAsciiDocsToFile() throws Exception {
        //    输出Ascii到单文件
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFile(Paths.get("./docs/asciidoc/generated/all"));
    }

    /**
     * 生成Markdown格式文档,并汇总成一个文件
     *
     * @throws Exception
     */
    @Test
    public void generateMarkdownDocsToFile() throws Exception {
        //    输出Markdown到单文件
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFile(Paths.get("./docs/markdown/generated/all"));
    }
}

说明

  • MarkupLanguage.ASCIIDOC：指定了要输出的最终格式。除了ASCIIDOC之外，还有MARKDOWN和CONFLUENCE_MARKUP
  • from(new URL(“http://localhost:8080/v2/api-docs”)：指定了生成静态部署文档的源头配置，可以是这样的URL形式，也可以是符合Swagger规范的String类型或者从文件中读取的流。如果是对当前使用的Swagger项目，我们通过使用访问本地Swagger接口的方式，如果是从外部获取的Swagger文档配置文件，就可以通过字符串或读文件的方式
  • toFolder(Paths.get("./docs/asciidoc/generated")：指定最终生成文件的具体目录位置
若相惜、不离不弃
关注
  • 0
    点赞
  • 踩
  • 1
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
四·C语言之·函数全方位理解
kikokingの比特宇宙
11-21 2704
函数是什么？ 在计算机科学中，子程序（英语：Subroutine, procedure, function, routine, method, subprogram, callable unit），是一个大型程序中的某部分代码， 由一个或多个语句块组成。它负责完成某项特定任务，而且相较于其他代 码，具备相对的独立性。 一般会有输入参数并有返回值，提供对过程的封装和细节的隐藏。这些代码通常被集成为软件库 自定义函数 如果库函数能干所有的事情，那还要程序员干什么?所有更加重要的是自定义函数。 自定.
冒泡排序、函数
weixin_71437031的博客
08-04 78
函数声明式function 函数名(){//函数体}函数表达式（赋值式）var 函数名 = function() {//函数体}调用函数函数名();函数声明的时候，函数体并不会执行，只有当函数被调用的时候才会执行两种声明的区别：声明式可以先调用再声明，赋值式必须先声明再调用函数传参//定义有参数的函数function 函数名(参数1,参数2){//函数体}//调用带有参数的函数函数名(参数1,参数2);/*函数定义时：函数名后面的参数为形参(形式参数)......
idea SpringBoot + Gradle 环境配置到项目打包
最新发布
yangchuang11的博客
05-13 1793
Gradle是一个基于ApacheAnt和ApacheMaven概念的项目自动化构建开源工具。它使用一种基于Groovy的特定领域语言(DSL)来声明项目设置，也增加了基于Kotlin语言的kotlin-based DSL，抛弃了基于XML的各种繁琐配置。面向Java应用为主。当前其支持的语言C++、Java、GroovyKotlinScala和Swift，计划未来将支持更多的语言。
JAVA新实战2：Gradle+Springboot多模块项目搭建
duihao的专栏
11-07 2862
本文以将在参照ruoyi若依系统代码架构的基础上进行优化，执行Gradle+Springboot多模块的项目搭建实践，成不成也就讲究着看吧，我们暂且命名为JoJava。开发工具IDE依据采用VSCode。掌握本文后，您可以对MAVEN下的多模块JAVA项目迁移到Gradle中有较直观的掌握，虽然本文以VSCode为开发工具，但核心代码同样适用于IntelliJ IDEA+Gradle。相关代码将持续更新到以下JoJava代码块仓库，免费开放给大家：jojava: 一些常用的java代码块集合。
Spring Boot整合Redis（gradle + gson + lombok + redisTemplate）
小龙在线
01-14 1027
本文创建了gradle项目，用来整合Spring Boot和Redis，用到了gradle + gson + lombok + redisTemplate等技术。
Java项目:学生管理系统(java+Springboot+Maven+mybatis+Vue+Mysql)
03-19
一、项目简述 本系统功能包括： 学生管理，教师管理，课程管理，成绩管理，系统管理等等。 二、项目运行 环境配置： ...Springboot + Maven + mybatis+ Vue 等等组成，B/S模式 + Maven管理等等。
springboot+hibernate+gradle+mysql的简单例子
07-10
相比Maven，Gradle提供了更灵活的构建配置，支持多项目构建和插件自定义。在这个项目中，Gradle用于管理项目的依赖，构建和打包应用程序。 4. **MySQL**：MySQL是一个广泛使用的开源关系型数据库管理系统。在这个...
SpringBoot+Maven 多模块项目的构建、运行、打包实战
08-27
SpringBoot+Maven 多模块项目的构建、运行、打包实战 本文主要介绍了 SpringBoot+Maven 多模块项目的构建、运行、打包实战，将 Maven 多模块项目与 SpringBoot 进行集成，通过一个实际的示例项目，展示了如何使用 ...
springboot+myabtis+maven+swagger
08-31
在本项目中，"springboot+myabtis+maven+swagger"的组合构建了一个现代、高效的后端服务，旨在简化API开发与管理。以下是这些技术的详细解释和相关知识点： 1. **Spring Boot**: Spring Boot是Spring框架的一个扩展...
golang swag 生成多个文档
白马啸西施
01-15 321
golang 通过swag生成多个文档
swagger 介绍及两种使用方法
热门推荐
程序猿-HZQ
04-26 22万+
一：swagger是什么？ 1、是一款让你更好的书写API文档的规范且完整框架。 2、提供描述、生产、消费和可视化RESTful Web Service。 3、是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。 二：使用第三方依赖（最简单的方法） 1、在pom.xml文件中添加第三方swagger依赖（） &amp;lt;dependen...
spring boot 整合 swagger自动生成接口文档，搬砖都快乐了~
FightingITPanda的博客
08-12 1090
spring boot 整合 swagger 自动生成接口文档，搬砖都快乐了~
gradle访问不到html,SpringBoot，Thymeleaf，Gradle：不访问静态资源，css没有显示(示例代码)...
weixin_42548829的博客
06-26 308
此时我已经尝试了很多东西，但我的CSS不会显示在我的页面上。这是我的百里香页面：Default Title这是我加载此页面时出现的错误，我认为这很重要：**2018-04-11 05:57:08.425 WARN 7904 --- [nio-8080-exec-2] o.s.web.servlet.PageNotFound : No mapping found for H...
swagger 生成接口文档，并导出html和pdf的过程
sunrj_niu的博客
09-29 1万+
swagger 生成接口文档，并导出html和pdf的过程 这里写目录标题swagger 生成接口文档，并导出html和pdf的过程swagger 生成接口文档swagger导出pdf和html解决乱码问题：**一、** swagger 生成接口文档 1.springboot版本： <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-b
Spring Boot - 2.spring boot整合Swageer
PxzBoss的博客
03-16 987
1.认识Swagger Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。 作用： 1. 接口的文档在线自动生成。 2. 功能测试。 2.Spring Boot整合Swagger POM.xml &amp;lt...
Spring boot + gradle + vue 前后端分离项目在linux服务器上部署运行
我真的超可爱的博客
05-18 749
1. spring-boot后台项目生成可执行jar文件 >> 首先确保springboot后台项目在本地环境中是可以正常跑起来的, buildscript { // 添加maven仓库 repositories { mavenLocal() // 阿里云的maven仓库 maven {url "http://maven.aliyun.com/nexus/content/groups/public/"} mavenCentral()//依赖Maven仓库 } ..
关于gradle与maven对springboot项目的配置文件加载异同
weixin_33973600的博客
04-12 1162
先说下缘由吧，由于年后跳槽换了家公司，构建项目工具也有maven改成gradle了，所以在搭建框架进行开发打包过程中难免会遇到一些意想不到的问题。 本文简述下打包扫描加载配置文件的异同吧。 maven打包加载配置文件的配置是在pom文件中配置： 1 <resources> 2 <resource> 3 ...
@ApiImplicitParam注解
aqx63777的博客
07-04 5257
@Api：用在请求的类上，表示对类的说明 tags="说明该类的作用，可以在UI界面上看到的注解" value="该参数没什么意义，在UI界面上也看到，所以不需要配置" @ApiOperation：用在请求的方法上，说明方法的用途、作用 value="说明方法的用途、作用" ...
java+springboot+maven+git
05-31
Java + Spring Boot + Maven + Git 是一种常见的开发技术栈，具体含义如下： 1. Java：Java 是一种跨平台的面向对象编程语言，被广泛用于Web应用程序、移动应用程序、桌面应用程序、嵌入式系统等领域。 2. Spring Boot：Spring Boot 是一种基于 Spring 框架的轻量级、快速开发的框架，它提供了一系列开箱即用的特性，让开发人员可以更快地搭建应用程序。 3. Maven：Maven 是一个项目管理工具，它可以自动化构建、测试、打包和部署 Java 项目。使用 Maven 可以方便地管理项目依赖和构建过程。 4. Git：Git 是一种分布式版本控制系统，它可以帮助开发人员协同开发、追踪代码变更、回滚代码等。使用 Git 可以更好地管理代码，提高代码质量和可维护性。 综上所述，Java + Spring Boot + Maven + Git 技术栈可以帮助开发人员快速构建高质量的应用程序，并且可以方便地管理项目依赖和代码变更。

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

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

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

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

抵扣说明：

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

余额充值