springboot2.x集成swagger

gekylin 发布于2019-08-16 17:37 / 1570人阅读

摘要：页面如下集成由于个人感觉原生的不太好看，网上提供了。

集成swagger pom包配置


    io.springfox
    springfox-swagger2
    2.9.2



    io.springfox
    springfox-swagger-ui
    ${swagger.version}

添加Swagger配置文件

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    /**
     * 创建一个Docket对象
     * 调用select()方法，
     * 生成ApiSelectorBuilder对象实例，该对象负责定义外漏的API入口
     * 通过使用RequestHandlerSelectors和PathSelectors来提供Predicate，在此我们使用any()方法，将所有API都通过Swagger进行文档管理
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //标题
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                //简介
                .description("")
                //服务条款
                .termsOfServiceUrl("")
                //作者个人信息
                .contact(new Contact("chenguoyu","","chenguoyu_sir@163.com"))
                //版本
                .version("1.0")
                .build();
    }
}

如果不想将所有的接口都通过swagger管理的话，可以将RequestHandlerSelectors.any()修改为RequestHandlerSelectors.basePackage()

配置静态访问资源

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 解决 swagger-ui.html 404报错
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
    }
}

到这里为止swagger就已经配置完了，可以启动项目，然后访问如下链接即可http://localhost:9000/swagger...

端口号applicationContext中设置的端口号。

页面如下

集成swagger-bootstrap-ui

由于个人感觉原生的swagger-ui不太好看，网上提供了swagger-bootstrap-ui。

pom依赖


    com.github.xiaoymin
    swagger-bootstrap-ui
    1.9.3

配置静态访问资源

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 解决 swagger-ui.html 404报错
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        // 解决 doc.html 404 报错
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");

    }
}

这时只需要访问以下链接即可http://localhost:9000/doc.html

swagger常用注解

@Api：用在类上，标志此类是Swagger资源

属性名称	备注
value	该参数没什么意义，在UI界面上不显示，所以不用配置
tags	说明该类的作用，参数是个数组，可以填多个
description	对api资源的描述

@ApiOperation：用在方法上，描述方法的作用

属性名称	备注
value	方法的用途和作用
tags	方法的标签，可以设置多个值
notes	方法的注意事项和备注
response	返回的类型（尽量不写，由swagger扫描生成）

@ApiImplicitParams：包装器：包含多个ApiImplicitParam对象列表

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

@ApiParam：用于Controller中方法的参数说明

属性名称	备注
name	属性名称
value	属性值
defaultValue	默认属性值
allowableValues	可以不配置
required	是否属性必填
allowMultiple	文件上传时，是否允许多文件上传

@ApiImplicitParam：定义在@ApiImplicitParams注解中，定义单个参数详细信息，如果只有一个参数，也可以定义在方法上

属性名称	备注
name	参数名
value	参数说明
dataType	参数类型
paramType	表示参数放在哪里 header : 请求参数的获取：@RequestHeader query : 请求参数的获取：@RequestParam path : 请求参数的获取：@PathVariable body : 不常用 form : 不常用
defaultValue	参数的默认值
required	参数是否必须传

@ApiModel：用在类上，表示对类进行说明，用于实体类中的参数接收说明

属性名称	备注
value	默认为类的名称
description	对该类的描述

@ApiModelProperty：在model类的属性添加属性说明

属性名称	备注
value	属性描述
name	属性名称
allowableValues	参数允许的值
dataType	数据类型
required	是否必填

@ApiResponses：包装器：包含多个ApiResponse对象列表

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

@ApiResponse：定义在@ApiResponses注解中，一般用于描述一个错误的响应信息

属性名称	备注
code	响应码
message	状态码对应的响应信息
response	默认响应类 Void
responseContainer	参考ApiOperation中配置

@ApiIgnore()：用于类或者方法上，不被显示在页面上

总结

除上面之外有点值得注意的是，如果是上传文件的话，需要把@ApiImplicitParam中的dataType属性配置为__File否则在swagger中会显示为文本框而不是上传按钮

如果需要项目代码，可以去我的github中下载；具体代码可以查看swagger目录

混合云私有云 swagger swagger+spring 轻量云服务器 swagger 云服务器jar包swagger

文章版权归作者所有，未经允许请勿转载,若此文章存在违规行为，您可以联系管理员删除。

转载请注明本文地址：https://www.ucloud.cn/yun/74623.html

SpringBoot 2.X Kotlin与Swagger2生成API文档

摘要：再通过函数创建的之后，用来创建该的基本信息这些基本信息会展现在文档页面中。函数返回一个实例用来控制哪些接口暴露给来展现，本例采用指定扫描的包路径来定义，会扫描该包下所有定义的，并产生文档内容除了被指定的请求。 showImg(http://download.qfeoo.com/kotlin_springboot_logo.png); 这里有个地方需要注意，在测试WebFlux集成Swa...

cyqian 2019-08-16 16:38 评论0 收藏0
ApiBoot - ApiBoot Swagger 使用文档

摘要：相关配置配置参数参数介绍默认值是否启用文档标题快速集成文档文档描述通过自动化配置快速集成文档，仅需一个注解一个依赖即可。注意通过所获取的类型都为。 ApiBoot是一款基于SpringBoot1.x，2.x的接口服务集成基础框架，内部提供了框架的封装集成、使用扩展、自动化完成配置，让接口开发者可以选着性完成开箱即用，不再为搭建接口框架而犯愁，从而极大...

yuanxin 2019-08-16 16:20 评论0 收藏0
Spring Data REST API集成Springfox、Swagger

摘要：请注意，截至目前版本，用于的集成仍处于孵化阶段，并且存在一些严重的错误和缺少的功能例如，请参阅此处和此处。响应可以使用和注解来调整不同的响应状态及其有效结论允许您在创建数据库驱动的时产生快速结果。原文: Documenting a Spring Data REST API with Springfox and Swagger 使用Spring Date REST，你可以迅速为Spr...

darcrand 2019-08-15 14:44 评论0 收藏0
SpringBoot非官方教程 | 第十一篇：SpringBoot集成swagger2，构建优雅的R

摘要：另外很容易构建风格的，简单优雅帅气，正如它的名字。配置一些基本的信息。三写生产文档的注解通过注解表明该接口会生成文档，包括接口名请求方法参数返回信息的等等。四参考资料中使用构建强大的文档 swagger,中文拽的意思。它是一个功能强大的api框架，它的集成非常简单，不仅提供了在线文档的查阅，而且还提供了在线文档的测试。另外swagger很容易构建restful风格的api，简单优雅帅气...

荆兆峰 2019-08-16 10:44 评论0 收藏0
Java | Spring Boot Swagger2 集成REST ful API 生成接口文档

摘要：集成生成接口文档原文简介由于的特性，用来开发变得非常容易，并且结合来自动生成文档变得方便快捷。使用生成，我们可以得到交互式文档。听过与的结合，生成更加完备的文档。接下来将基于与搭建完整的文档系统。 Spring Boot Swagger2 集成REST ful API 生成接口文档原文简介由于Spring Boot 的特性，用来开发 REST ful 变得非常容易，并且结合 Sw...

joyvw 2019-08-16 10:56 评论0 收藏0