开发者社区> l1ka> 正文

spring boot 下swagger2 的使用

简介: Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。 swagger 官方Demo供参考 https://petstore.swagger.io/ swagger注解 swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等。 API详细说明 @Api(tags = "收付费方式变更") 常用 @ApiOperation("获取用户列表") 常用 @ApiParam(v
+关注继续查看

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。


swagger 官方Demo供参考


https://petstore.swagger.io/


swagger注解


swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等。


image.png


API详细说明


@Api(tags = "收付费方式变更") 常用


@ApiOperation("获取用户列表") 常用


@ApiParam(value = "用户Id") 常用


@ApiImplicitParam:


作用在方法上,表示单独的请求参数, 一个非常强大且重要的注解, 作用和ApiParam类似


开始使用



pom中导入dependency

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>


  1. Application 中启用 @EnableSwagger2


  1. config的配置类

package com.abc.xxx;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
/**
 * @author zh
 * @ClassName cn.saytime.Swgger2
 * @Description
 * @date 2017-07-10 22:12:31
 */
@Configuration
public class Swagger2 {
    private static final String SWAGGER_SCAN_BASE_PACKAGE = "com.baomidou.ant.abc";
    private static final String VERSION = "0.0.1";
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select() // 选择那些路径和api会生成document
                .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
                .paths(PathSelectors.any())// 对根下所有路径进行监控
                .build();
    }
    private static ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .version(VERSION)
                .build();
    }
}


/**
 * <p>
 * 收付费方式变更总表
 前端控制器
 * </p>
 *
 * @author someone
 * @since 2019-07-15
 */
@Api(tags = "收付费方式变更")
@RestController
@RequestMapping("/test")
public class PaychangeTotalController {
    /**
     * 查询用户列表
     *
     * @return
     */
    @ApiOperation("获取用户列表")
    @GetMapping("/users/{id}")
    public String getUserList(@ApiParam(value = "用户", required = true) @PathVariable String id) {
        return "Npp";
    }
    @ApiOperation("小猫变小狗")
    @PostMapping( value = "/edit")
    public Result<?> edit (@RequestBody Cat cat){
        Dog dog = new Dog();
        dog.setNickName("小白");
        return JSONResult.ok(dog);
    }
}


总结常用swagger-ui注解


image.png


@Api() 用于类


该注解将一个Controller(Class)标注为一个swagger资源(API)。在默认情况下,Swagger-Core只会扫描解析具有@Api注解的类,而会自动忽略其他类别资源(JAX-RS endpoints,Servlets等等)的注解。该注解包含以下几个重要属性:


  • tags:API分组标签。具有相同标签的API将会被归并在一组内展示。


  • value:如果tags没有定义,value将作为Api的tags使用


  • description:对该API的详细描述信息


  • position:如果一个controller中有多个请求方法,可以通过该属性来指定API在swagger-ui中的显示顺序


@ApiOperation() 用于方法


在指定的(路由)路径上,对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。此注解的属性有:


  • value:对操作的简单说明,长度为120个字母,60个汉字。


  • notes:对操作的详细说明。


  • httpMethod:HTTP请求的动作名,可选值有:"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"。


code:默认为200,有效值必须符合标准的HTTP Status Code Definitions。


@ApiParam() 用于方法,参数,字段说明


增加对参数的元信息说明,主要的属性有:


required:指定该参数是否为必传参数


value:对该参数含义的简短说明


@ApiResponses()用于包装类


注解@ApiResponse的包装类,数组结构。


即使需要使用一个@ApiResponse注解,也需要将@ApiResponse注解包含在注解@ApiResponses内。


@ApiResponse()用于方法的返回结果


描述一个操作可能的返回结果。


当REST API请求发生时,这个注解可用于描述所有可能的成功与错误码。


可以用,也可以不用这个注解去描述操作的返回类型,但成功操作的返回类型必须在@ApiOperation中定义。


如果API具有不同的返回类型,那么需要分别定义返回值,并将返回类型进行关联。


但Swagger不支持同一返回码,多种返回类型的注解。注意:这个注解必须被包含在@ApiResponses注解中。


字段说明:


code:HTTP请求返回码。有效值必须符合标准的HTTP Status Code Definitions。


message:用于对返回信息作详细说明,对请求结果的描述信息


response:返回类型信息,必须使用完全限定类名,比如


“com.xyz.cc.Person.class”。


responseContainer:如果返回类型为容器类型,可以设置相应的值。有效值为 "List",


"Set" or "Map",其他任何无效的值都会被忽略


2)Model的注解


@ApiModel() 用于类


提供对Swagger model额外信息的描述。在标注@ApiOperation注解的操作内,所有的类将自动被内省(introspected),但利用这个注解可以做一些更加详细的model结构说明。主要属性有:


value:model的别名,默认为类名


description:对model的详细描述


** @ApiModelProperty() 用于model类的属性**


表示对model属性的说明或者数据操作更改,主要的属性有:


value:描述


required:标识该属性是否为必须值


example:给出该属性的示例值


allowableValues : 可选值, 像这样@ApiModelProperty(allowableValues = "range[1,5]") 或者 @ApiModelProperty(allowableValues = "111, 222")

3)其他注解


@ApiIgnore() 用于类,方法,方法参数


表示这个方法或者类被忽略


  • @ApiImplicitParam() 用于方法


表示单独的请求参数


  • @ApiImplicitParams() 用于方法


该注解可以包含多个 @ApiImplicitParam


swagger2 如何匹配多个controller

@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.shubing"))
            .paths(PathSelectors.any())
            .build();
}


或者

@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
            .paths(PathSelectors.any())
            .build();
}


使用以下两种,都是错误的

@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.shubing.*.controller"))
            .paths(PathSelectors.any())
            .build();
}
@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.shubing.course.controller"))
            .apis(RequestHandlerSelectors.basePackage("com.shubing.user.controller"))
            .paths(PathSelectors.any())
            .build();
}


不同环境中配置是否启用swagger

@Value("${swagger.enable}")
private boolean enableSwagger;
@Bean 
public Docket customImplementation(){
    return new Docket(SWAGGER_2)
        .apiInfo(apiInfo())
        .enable(enableSwagger) //<--- Flag to enable or disable possibly loaded using a property file
        .includePatterns(".*pet.*");
}


然后,需要在dev和test环境中配置:

swagger:
  enable: true



版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

相关文章
如何设置阿里云服务器安全组?阿里云安全组规则详细解说
阿里云安全组设置详细图文教程(收藏起来) 阿里云服务器安全组设置规则分享,阿里云服务器安全组如何放行端口设置教程。阿里云会要求客户设置安全组,如果不设置,阿里云会指定默认的安全组。那么,这个安全组是什么呢?顾名思义,就是为了服务器安全设置的。安全组其实就是一个虚拟的防火墙,可以让用户从端口、IP的维度来筛选对应服务器的访问者,从而形成一个云上的安全域。
19650 0
阿里云服务器如何登录?阿里云服务器的三种登录方法
购买阿里云ECS云服务器后如何登录?场景不同,阿里云优惠总结大概有三种登录方式: 登录到ECS云服务器控制台 在ECS云服务器控制台用户可以更改密码、更换系.
28957 0
阿里云服务器安全组设置内网互通的方法
虽然0.0.0.0/0使用非常方便,但是发现很多同学使用它来做内网互通,这是有安全风险的,实例有可能会在经典网络被内网IP访问到。下面介绍一下四种安全的内网互联设置方法。 购买前请先:领取阿里云幸运券,有很多优惠,可到下文中领取。
22473 0
阿里云服务器端口号设置
阿里云服务器初级使用者可能面临的问题之一. 使用tomcat或者其他服务器软件设置端口号后,比如 一些不是默认的, mysql的 3306, mssql的1433,有时候打不开网页, 原因是没有在ecs安全组去设置这个端口号. 解决: 点击ecs下网络和安全下的安全组 在弹出的安全组中,如果没有就新建安全组,然后点击配置规则 最后如上图点击添加...或快速创建.   have fun!  将编程看作是一门艺术,而不单单是个技术。
20616 0
阿里云服务器ECS登录用户名是什么?系统不同默认账号也不同
阿里云服务器Windows系统默认用户名administrator,Linux镜像服务器用户名root
16310 0
腾讯云服务器 设置ngxin + fastdfs +tomcat 开机自启动
在tomcat中新建一个可以启动的 .sh 脚本文件 /usr/local/tomcat7/bin/ export JAVA_HOME=/usr/local/java/jdk7 export PATH=$JAVA_HOME/bin/:$PATH export CLASSPATH=.
14893 0
使用OpenApi弹性释放和设置云服务器ECS释放
云服务器ECS的一个重要特性就是按需创建资源。您可以在业务高峰期按需弹性的自定义规则进行资源创建,在完成业务计算的时候释放资源。本篇将提供几个Tips帮助您更加容易和自动化的完成云服务器的释放和弹性设置。
20893 0
+关注
340
文章
0
问答
文章排行榜
最热
最新
相关电子书
更多
JS零基础入门教程(上册)
立即下载
性能优化方法论
立即下载
手把手学习日志服务SLS,云启实验室实战指南
立即下载