Spring Boot使用com.spring4all整合Swagger

y_bccl27

已于 2023-03-22 21:23:24 修改

阅读量2k

点赞数

分类专栏： Spring Boot 文章标签： spring boot

于 2020-04-24 13:14:17 首次发布

本文链接：https://blog.csdn.net/y_bccl27/article/details/105726501

版权

Spring Boot 专栏收录该内容

29 篇文章 0 订阅

订阅专栏

第一步：使用Swagger之前需要我们先新建一个SpringBoot项目，接口API是RESTful 风格

第二步：在pom.xml中引入swagger的依赖，当前版本为1.9.0

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

第三步：主启动类上添加 @EnableSwagger2Doc注解

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import com.spring4all.swagger.EnableSwagger2Doc;

@SpringBootApplication
@EnableSwagger2Doc
public class Swager2Application {
	public static void main(String[] args) {
		SpringApplication.run(Swager2Application.class, args);
	}
}

第四步：在yum文件或者application.properties文件中添加swagger的配置信息

各个配置参数说明：

swagger.enabled：表示是否开启swagger，true为开启，false为不开启

swagger.title：接口文档的标题

swagger.description：接口文档的描述

swagger.license：许可证，一般默认取值为Apache License,Version 2.0

swagger.licenseUrl：许可证URL，一般默认取值为Apache License, Version 2.0

swagger.terms-of-service-url：服务条款URL，一般默认取值为GitHub - SpringForAll/spring-boot-starter-swagger: 自制spring boot starter for swagger 2.x，来试试吧，很好用哦~

swagger.contact.name：接口维护人姓名

swagger.contact.url：接口维护人的Url，一般情况下这个地方为空就行

swagger.contact.email：接口维护人的邮箱

swagger.base-package：指定swagger扫描的基础包，默认：全扫描

swagger.base-path：需要处理的基础URL规则，默认：/**

swagger.exclude-path：指定在basePath基础上需要排除的url规则，配置文件中可不配置该字段，示例写法为：swagger.exclude-path=/error,/ops/**

swagger.version：指定当前接口文档的版本

yml文件中的配置示例（推荐使用该种配置方式）

#swagger配置
swagger:
  enabled: true
  title: 
  description: 
  license: Apache License,Version 2.0
  license-url: https://www.apache.org/licenses/LICENSE-2.0.html
  terms-of-service-url: https://github.com/dyc87112/spring-boot-starter-swagger
  contact:
    name: 
    url: 
    email: 
  base-package: com.*.controller
  base-path: /**
  version:

application.properties文件的配置示例

swagger.title=
swagger.description=
swagger.version=
swagger.license=Apache License, Version 2.0
swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html
swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger
swagger.contact.name=
swagger.contact.url=
swagger.contact.email=
swagger.base-package=com.example.controller
swagger.base-path=/**

第五步：启动项目，在浏览器中打开http://localhost:8080/swagger-ui.html（一般的访问路径为http://ip:端口号/项目名/swagger-ui.html），启动成功以后效果如下图所示

常用注解说明：

@Api(tags = "xxx",description="description about xxx") :该注解作用于Controller类上面，tags的取值表示给该Controller类取一个标签名为"xxx"

@ApiOperation(value="提交信息",notes="提交用户填写的信息至后台")：该注解作用于方法上，value的取值说明方法的用途，notes表示方法的备注说明

@ApiModel(description=“x”)和@ApiModelProperty(“x”)：是用来给实体类添加说明，使用该注解时一定要注意该实体类一定是被作为请求体传递到Controller中，否则的话，即使添加了该注解在h5文档页面也不会有任何效果

@Data
@ApiModel(description="用户实体类")
public class User {
    @ApiModelProperty("姓名")
    private String name;
    @ApiModelProperty("年龄")
    private Integer age;
}

@ApiParam：该注解作用在请求参数处，value表示该请求参数的描述，required表示该请求参数是否必传

@RequestMapping(value = "/qryUser",method = RequestMethod.POST)
public CommonResult qryUser(@RequestBody @ApiParam(value = "用户请求实体",required = true) User user) {
    String id = request.getId();
    return userService.qryUser(id);
}

@ApiImplicitParams与@ApiImplicitParam：@ApilmplicitParams注解用在请求的方法上，包含一组参数说明，@ApilmplicitParam用在 @ApiImplicitParams 注解中，指定一个请求参数的配置信息

name：表示参数名

value：该参数的汉字说明解释

required：该参数是否必须传

paramType：该参数放在那个地方，其取值有header、query、path、body（不常用）和form（不常用）

值为“header”时，表示该请求参数是从@RequestHeader中获取；

值为“query”时，表示该请求参数是从@RequestParam中获取；

值为“path”时，表示该请求参数是从@PathVariable中获取

dataType：参数类型，默认String，其它值dataType="Integer"

defaultValue：参数的默认值

@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")
})

注意：在使用swagger的插件时，一定要先在pom.xml中导入swagger的依赖，其次再在pom.xml中引入其插件

swagger2markup官网参数配置地址：Swagger2Markup Documentation

<!--引入swagger2markup的插件-->
<plugin>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup-maven-plugin</artifactId>
    <version>1.3.1</version>
    <configuration>
        <!-- 指定生成静态部署文档的源头配置url -->
        <swaggerInput>http://localhost:8080/项目名/v2/api-docs</swaggerInput>
        <!--指定生成的路径-->
        <outputFile>D:\test\接口文档</outputFile>
        <config>
            <!-- 指定最终要输出的格式，除了ASCIIDOC之外，还有MARKDOWN和CONFLUENCE_MARKUP -->                              
            <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
            <!--设置目录的展现方式: AS_IS, TAGS-->
            <swagger2markup.pathsGroupedBy>AS_IS</swagger2markup.pathsGroupedBy>
            <!--是否输出request示例和response示例，默认不开启-->
            <swagger2markup.generatedExamplesEnabled>false</swagger2markup.generatedExamplesEnabled>
            <!--输出文件的展示语言 ZH, EN, RU, FR, DE, TR, ES, BR, JA-->
            <swagger2markup.outputLanguage>ZH</swagger2markup.outputLanguage>
        </config>
    </configuration>
</plugin>

<!--引入asciidoctor的插件-->
<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.6</version>
    <configuration>
        <!--获取该目录下所有的adoc文件-->
        <sourceDirectory>D:\test</sourceDirectory>
        <!--将生成的文件保存到该文件下面-->
        <outputDirectory>D:\test2</outputDirectory>
        <!-- 指定生成文件的格式，常见有html、html5 -->
        <backend>html</backend>
        <sourceHighlighter>coderay</sourceHighlighter>
        <attributes>
            <!-- 指定生产的接口文档的菜单栏的位置，left在左边，right在右边 -->
            <toc>left</toc>
            <!--显示层级数，不设置时默认为2-->
            <toclevels>3</toclevels>
            <!--自动打数字序号，true表示开启，false表示不开启-->
            <sectnums>true</sectnums>
        </attributes>
    </configuration>
</plugin>

在swagger2markup插件下面点击swagger2markup:convertSwagger2markup 时会在指定的文件夹中生成对应的文件