首页
学习
活动
专区
工具
TVP
发布
社区首页 >专栏 >Spring Boot 2.x(十二):Swagger2 的正确玩儿法

Spring Boot 2.x(十二):Swagger2 的正确玩儿法

作者头像
山禾说
发布2019-03-15 16:36:00
3430
发布2019-03-15 16:36:00
举报
文章被收录于专栏:Vi的技术博客Vi的技术博客

Swagger2简介

简单的来说,Swagger2的诞生就是为了解决前后端开发人员进行交流的时候API文档难以维护的痛点,它可以和我们的Java程序完美的结合在一起,并且可以与我们的另一开发利器Spring Boot来配合使用。

开始使用

第一步:导入POM文件
         <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency> 

        <!-- 这里使用 swagger-bootstrap-ui 替代了原有丑陋的ui,拯救处女座~ -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.0</version>
        </dependency>
第二步:添加配置类

我们需要新增一个Swagger2Config 的配置类:

/**
 *    Swagger2 配置类
 * @author vi    
 * @since 2019/3/6 8:31 PM
 */
@Configuration
public class Swagger2Config {

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

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("viboot-swagger2")    //标题
                .description("Restful-API-Doc")    //描述
                .termsOfServiceUrl("https://www.cnblogs.com/viyoung") //这里配置的是服务网站,我写的是我的博客园站点~欢迎关注~
                .contact(new Contact("Vi的技术博客", "https://www.cnblogs.com/viyoung", "18530069930@163.com")) // 三个参数依次是姓名,个人网站,邮箱
                .version("1.0") //版本
                .build();
    }
}
第三步:在启动类中添加配置

注意一定要记得添加@EnableSwagger2注解

/**
 * @author vi
 * @since 2019/3/6 6:35 PM
 */
@SpringBootApplication
@ComponentScan(value = "indi.viyoung.viboot.*")
@MapperScan(value = "indi.viyoung.viboot.swagger2.mapper")
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class ViBootSwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(ViBootSwaggerApplication.class, args);
    }
}
第四步:通过注解来完成API文档
1. @Api

注解名称

注解属性

作用域

属性作用

@Api

tags

说明该类的作用

value

说明该类的作用

举个?:

@Api(value = "用户类控制器",tags="用户类控制器")
public class UserController {
...
}
2 . @ApiOperation

注解名称

注解属性

作用域

属性作用

@ApiOperation()

value

方法

描述方法作用

notes

方法

提示内容

tags

方法

分组

举个?:

@ApiOperation(value = "获取用户列表",notes = "获取用户列表")
public List<User> get() {
     ...   
}
3. @ApiParam

注解名称

注解属性

作用域

属性作用

@ApiParam()

name

方法参数

参数名

value

方法参数

参数说明

required

方法参数

是否必填

举个?:

@ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
public User get(@ApiParam(name="id",value="用户id",required=true) Long id) {
    log.info("GET..{}...方法执行。。。",id);
    return userService.getById(id);
}
4. @ApiModel && @ApiModelProperty

注解名称

注解属性

作用域

属性作用

@ApiModel()

value

对象名

description

描述

@ApiModelProperty()

value

方法

字段说明

name

方法

属性名

dataType

方法

属性类型

required

方法

是否必填

example

方法

举例

hidden

方法

隐藏

举个?:

@ApiModel(value="user对象",description="用户对象user")
public class User implements Serializable {

    private static final long serialVersionUID = 1L;

    @TableId(value = "id", type = IdType.AUTO)
    @ApiModelProperty(value = "用户ID",example = "1000001",hidden=true)
    private Long id;

    @ApiModelProperty(value="用户名",required = true,dataType = "String")
    private String userName;

    @ApiModelProperty(value = "密码")
    private String password;
}
5. @ApiImplicitParam && @ApiImplicitParams

@ApiImplicitParam可以单个用于方法之上,多个参数的话可以把@ApiImplicitParam放到@ApiImplicitParams中,这里只罗列@ApiImplicitParam的属性:

注解名称注解属性作用域属性作用@ApiImplicitParam()value方法参数说明
name方法参数名
dataType方法数据类型
paramType方法参数类型
example方法举例

举个?:

    @ApiImplicitParams({
            @ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User")
    })
    public void put(User user) {
        userService.updateById(user);
        log.info("PUT方法执行。。。");
    }

这里需要注意一点,我们并没有在注解中写图中圈中的两个参数,这个是去读取了我们刚刚为User类的注解,并将用户名设置为必填!

6.@ApiResposne && @ApiResponses

@ApiResponses@ApiResponse的关系和@ApiImplicitParam && @ApiImplicitParams 的关系和用法都是类似的

注解名称

注解属性

作用域

属性作用

@ApiResponse()

response

方法

返回类

code

方法

返回码

message

方法

返回信息

examples

方法

例子

最后再聊聊这个UI

先贴几张spring-fox的ui(正是我们所熟知的那一套)

相信看到这里,大家心里对于这两套UI的选择应该都有个答案了(PS:不排除和我的审美不一致的~),个人觉得bootstrap风格的ui不仅好看,而且有各种强大的功能~

  • 导出md文档
  • 参数缓存

原创文章,文笔有限,才疏学浅,文中若有不正之处,万望告知。

本文参与 腾讯云自媒体分享计划,分享自微信公众号。
原始发表:2019-03-09,如有侵权请联系 cloudcommunity@tencent.com 删除

本文分享自 Vi的技术博客 微信公众号,前往查看

如有侵权,请联系 cloudcommunity@tencent.com 删除。

本文参与 腾讯云自媒体分享计划  ,欢迎热爱写作的你一起参与!

评论
登录后参与评论
0 条评论
热度
最新
推荐阅读
目录
  • Swagger2简介
  • 开始使用
    • 第一步:导入POM文件
      • 第二步:添加配置类
        • 第三步:在启动类中添加配置
          • 第四步:通过注解来完成API文档
            • 1. @Api
            • 2 . @ApiOperation
            • 3. @ApiParam
            • 4. @ApiModel && @ApiModelProperty
            • 5. @ApiImplicitParam && @ApiImplicitParams
            • 6.@ApiResposne && @ApiResponses
        • 最后再聊聊这个UI
        领券
        问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档