swagger 配置教程

喻增

2023-12-01

第一步引入相关pom

<dependency>
            <groupId>com.spring4all</groupId>
            <artifactId>swagger-spring-boot-starter</artifactId>
            <version>1.9.0.RELEASE</version>
        </dependency>

第二步 swagger配置

以下是最基础的配置

swagger.enabled= true
swagger.base-package= com.***.controller
swagger.title= 测试接口
swagger.version= 0.0.1-SNAPSHOT
swagger.description= 测试使用
swagger.contact.name= rubik

第三步启用swagger

使用该注解，启用swagger

@EnableSwagger2Doc

第四步编写swagger接口文档

接口类文档注解
@Api(value = "采购查询成功率api接口", description = "采购查询成功率api接口")

方法文档注解
@ApiOperation(value = "查询成功率", notes = "查询成功率")

参数文档注解
@ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "supplyId", dataType = "int", required = true, value = "供应商id"),
            @ApiImplicitParam(paramType = "query", name = "orderId", dataType = "String", required = true, value = "订单号")
    })

或者在参数实体类内部的属性上面直接注解
@ApiModelProperty(value = "订单号", required = true)

返回值文档注解
@ApiResponses({
            @ApiResponse(code = 200, message = "响应成功", response = SyncStockResponseDTO.class)
    })

返回值对象中属性文档注解
@ApiModelProperty(notes = "当前批次库存，通驰数字专有", dataType = "int")

常用注解说明

Api
ApiModel
ApiModelProperty
ApiOperation
ApiParam
ApiResponse
ApiResponses
ResponseHeader

Api

Api 用在类上，说明该类的作用。可以标记一个Controller类做为swagger 文档资源，使用方式：

@Api(value = "/user", description = "Operations about user")

与Controller注解并列使用。属性配置：

属性名称	备注
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
produces	For example, "application/json, application/xml"
consumes	For example, "application/json, application/xml"
protocols	Possible values: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏

在SpringMvc中的配置如下：

@Controller
@RequestMapping(value = "/api/pet", produces = {APPLICATION_JSON_VALUE, APPLICATION_XML_VALUE})
@Api(value = "/pet", description = "Operations about pets")
public class PetController {

}

ApiOperation标记

ApiOperation：用在方法上，说明方法的作用，每一个url资源的定义,使用方式：

@ApiOperation(
          value = "Find purchase order by ID",
          notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
          response = Order,
          tags = {"Pet Store"})

与Controller中的方法并列使用。属性配置：

属性名称	备注
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
produces	For example, "application/json, application/xml"
consumes	For example, "application/json, application/xml"
protocols	Possible values: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏
response	返回的对象
responseContainer	这些对象是有效的 "List", "Set" or "Map".，其他无效
httpMethod	"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
code	http的状态码默认 200
extensions	扩展属性

在SpringMvc中的配置如下：

@RequestMapping(value = "/order/{orderId}", method = GET)
  @ApiOperation(
      value = "Find purchase order by ID",
      notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
      response = Order.class,
      tags = { "Pet Store" })
   public ResponseEntity<Order> getOrderById(@PathVariable("orderId") String orderId)
      throws NotFoundException {
    Order order = storeData.get(Long.valueOf(orderId));
    if (null != order) {
      return ok(order);
    } else {
      throw new NotFoundException(404, "Order not found");
    }
  }

ApiParam标记

ApiParam请求属性,使用方式：

public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true)  User user)

与Controller中的方法并列使用。

属性配置：属性名称 | 备注 ------- | ------- name | 属性名称 value | 属性值 defaultValue | 默认属性值 allowableValues | 可以不配置 required | 是否属性必填 access | 不过多描述 allowMultiple | 默认为false hidden | 隐藏该属性 example | 举例子在SpringMvc中的配置如下：

public ResponseEntity<Order> getOrderById(
      @ApiParam(value = "ID of pet that needs to be fetched", allowableValues = "range[1,5]", required = true)
      @PathVariable("orderId") String orderId)

ApiResponse

ApiResponse：响应配置，使用方式：

@ApiResponse(code = 400, message = "Invalid user supplied")

与Controller中的方法并列使用。属性配置：属性名称 | 备注 ------- | ------- code | http的状态码 message | 描述 response | 默认响应类 Void reference | 参考ApiOperation中配置 responseHeaders | 参考 ResponseHeader 属性配置说明 responseContainer | 参考ApiOperation中配置在SpringMvc中的配置如下：

@RequestMapping(value = "/order", method = POST)
  @ApiOperation(value = "Place an order for a pet", response = Order.class)
  @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
  public ResponseEntity<String> placeOrder(
      @ApiParam(value = "order placed for purchasing the pet", required = true) Order order) {
    storeData.add(order);
    return ok("");
  }

ApiResponses

ApiResponses：响应集配置，使用方式：

@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
与Controller中的方法并列使用。 属性配置：

属性名称	备注
value	多个ApiResponse配置

在SpringMvc中的配置如下：

@RequestMapping(value = "/order", method = POST)
  @ApiOperation(value = "Place an order for a pet", response = Order.class)
  @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
  public ResponseEntity<String> placeOrder(
      @ApiParam(value = "order placed for purchasing the pet", required = true) Order order) {
    storeData.add(order);
    return ok("");
  }

ResponseHeader

响应头设置，使用方法

@ResponseHeader(name="head1",description="response head conf")

与Controller中的方法并列使用。属性配置：

属性名称	备注
name	响应头名称
description	头描述
response	默认响应类 Void
responseContainer	参考ApiOperation中配置

在SpringMvc中的配置如下：

@ApiModel(description = "群组")

其他

@ApiImplicitParams：用在方法上包含一组参数说明；
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
- paramType：参数放在哪个地方
- name：参数代表的含义
- value：参数名称
- dataType：参数类型，有String/int，无用
- required ：是否必要
- defaultValue：参数的默认值
@ApiResponses：用于表示一组响应；
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息；
- code：响应码(int型)，可自定义
- message：状态码对应的响应信息
@ApiModel：描述一个Model的信息(这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候；
@ApiModelProperty：描述一个model的属性。

利用swagger生成静态的api文档

引入依赖

<dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.1</version>
        </dependency>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-pdf</artifactId>
            <version>1.5.0-alpha.10.1</version>
            <scope>test</scope>
        </dependency>

配置插件

插件一

<plugin>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <version>1.3.1</version>
                <configuration>
                    <swaggerInput>http://localhost:10086/v2/api-docs</swaggerInput>
                    <outputDir>src/docs/asciidoc/generated</outputDir>
                    <config>
                        <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                    </config>
                </configuration>
            </plugin>

插件二

<plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.6</version>
                <configuration>
                    <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
                    <outputDirectory>src/docs/asciidoc/html</outputDirectory>
                    <backend>html</backend>
                    <sourceHighlighter>coderay</sourceHighlighter>
                    <attributes>
                        <!--导航栏在左-->
                        <toc>left</toc>
                        <!--显示层级数-->
                        <toclevels>3</toclevels>
                        <!--自动打数字序号-->
                        <sectnums>true</sectnums>
                    </attributes>
                </configuration>
            </plugin>

编写测试类

package com.ccservice.searchstatistical;

import io.github.swagger2markup.GroupBy;
import io.github.swagger2markup.Language;
import io.github.swagger2markup.Swagger2MarkupConfig;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import io.github.swagger2markup.markup.builder.MarkupLanguage;
import org.asciidoctor.cli.AsciidoctorInvoker;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;

import java.net.MalformedURLException;
import java.net.URL;
import java.nio.file.Paths;

@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
public class TestApplication {

    /**
     * 生成AsciiDocs格式文档
     * @throws Exception
     */
    @Test
    public void generateAsciiDocs() throws Exception {
        //    输出Ascii格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withGeneratedExamples()
                .withPathsGroupedBy(GroupBy.TAGS)
                .withOutputLanguage(Language.ZH)//设置语言中文还是其他语言
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)//设置生成格式
                .withoutInlineSchema()
                .build();

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

    @Test
    public void generatePDF() {
        //样式
        String style = "pdf-style=E:\\themes\\theme.yml";
        //字体
        String fontsdir = "pdf-fontsdir=E:\\fonts";
        //需要指定adoc文件位置
        String adocPath = "E:\\all.adoc";
        AsciidoctorInvoker.main(new String[]{"-a",style,"-a",fontsdir,"-b","pdf",adocPath});
    }


    /**
     * 生成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:10086/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFile(Paths.get("src/docs/asciidoc/generated/api"));
    }
    /**
     * 生成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:10086/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFile(Paths.get("src/docs/asciidoc/generated/api"));
    }

    /**
     * 生成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:10086/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFile(Paths.get("src/docs/asciidoc/generated/api"));
    }

    /**
     * 生成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:10086/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFile(Paths.get("src/docs/asciidoc/generated/api"));
    }

}

通过插件生成文档

生成ASCIIDOC等，效果等同上面代码

<plugin>
				<groupId>io.github.swagger2markup</groupId>
				<artifactId>swagger2markup-maven-plugin</artifactId>
				<version>1.3.4</version>
				<configuration>
					<swaggerInput>http://localhost:9090/v2/api-docs</swaggerInput><!---swagger-api-json路径-->
					<outputDir>./docs/asciidoc/generated</outputDir><!---生成路径-->
                    <outputFile>src/docs/asciidoc/generated/all</outputFile><!--生成文件-->						
                    <config>
					        <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage><!--生成格式-->
					</config>
				</configuration>
			</plugin>

mvn执行swagger2markup:convertSwagger2markup 若遇到问题java.lang.NoClassDefFoundError: org/pegdown/PegDownProcessor修改swagger2markup-maven-plugin-1.3.4.pom增加

<dependency>
			<groupId>org.pegdown</groupId>
			<artifactId>pegdown</artifactId>
			<version>1.4.2</version>
		</dependency>

生成html(前提是已经存在ASCIIDOC)

<plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.6</version>
                <configuration>
                    <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
                    <outputDirectory>src/docs/asciidoc/html</outputDirectory>
                    <backend>html</backend>
                    <sourceHighlighter>coderay</sourceHighlighter>
                    <attributes>
                        <!--导航栏在左-->
                        <toc>left</toc>
                        <!--显示层级数-->
                        <toclevels>3</toclevels>
                        <!--自动打数字序号-->
                        <sectnums>true</sectnums>
                    </attributes>
                </configuration>
            </plugin>

注意

idea的配置文件有可能会导致乱码问题，解决swagger乱码问题，请看这篇文章

使用IDEA搭建SwaggerUI 中文乱码解决！

修改完后，记得将中文全部删除，重新输入中文，方可彻底解决乱码。

如果还是有乱码问题，那就使用英文吧，api文档用英文的，多高大尚

swagger 配置教程

第一步引入相关pom

第二步 swagger配置

第三步启用swagger

第四步编写swagger接口文档

常用注解说明

Api

ApiOperation标记

ApiParam标记

ApiResponse

ApiResponses

ResponseHeader

其他

利用swagger生成静态的api文档

引入依赖

配置插件

编写测试类

通过插件生成文档

注意

相关阅读

相关文章

相关问答

相关文档

swagger 配置教程

第一步 引入相关pom

第二步 swagger配置

第三步 启用swagger

第四步 编写swagger接口文档

常用注解说明

Api

ApiOperation标记

ApiParam标记

ApiResponse

ApiResponses

ResponseHeader

其他

利用swagger生成静态的api文档

引入依赖

配置插件

编写测试类

通过插件生成文档

注意

相关阅读

相关文章

相关问答

相关文档

第一步引入相关pom

第三步启用swagger

第四步编写swagger接口文档