Mephisto

个人站

欢迎来到我的个人站~


Spring Boot学习记录(二)

Spring Boot 与 swagger

​ 网上关于swagger 有着很多的介绍与使用帮助,因此本文将不会花费太多的笔墨去介绍swagger 是什么,它有什么好处,我们只需要知道swagger 可以为我们提供一个动态的可视化文档,所见即所得的更新我们的 API,并提供详细使用文档的一个工具就好了。

Spring Boot 集成 swagger

在项目的pom.xml文件中导入 swagger 的相关依赖:

  <!--swagger -->
  <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.9.2</version>
  </dependency>
  <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>2.9.2</version>
  </dependency>

swagger相关包导入完成之后我们还需要专门为它写一个配置文件,用于设置一些个性化的相关内容,在项目工程中新建一个配置包,和一个配置文件SwaggerConfig.java,如图:

文件内容为:


/**
 * @program: acgpicture
 * @description: Swagger配置类
 * @author: Mephisto
 * @create: 2019-04-17 15:06
 **/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
  
    @Bean
    public Docket api() {
      
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("团队名称")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("文档标题")
                .contact(new Contact("联系人名称", "", "联系人邮箱(xxx@xxx.xxx)"))
                .version("Api 版本").build();
    }

}

不要忘记写注解,不然 Spring Boot 是不会帮我们加载该配置的,到这一步,swagger的配置就基本完成了,是不是很简单呢?然后我们运行起服务器来看一下吧!

​ 启动服务器后浏览器中输入默认的网址:http://localhost:8080/swagger-ui.html,一切顺利的话可以看到这样的界面:

这样一来的话我们的swagger就算是集成成功了,下面让我们来使用它,看它怎样为我们的减少沟通成本,提升开发效率!

​ 我们新建一个控制器包与一个主页类HomeController.java,将原来的 hello world 方法转移到该类下,代码如下:

@RestController
public class HomeController {

    @GetMapping("/index")
    String index() {
        return "hello world";
    }
}

需要注意的是@RestController是一个组合注解,包含@Controller:这是一个控制器,@ResponseBody:需要输出到浏览器这两个注解,而@GetMapping注解是@RequestMapping(method = RequestMethod.GET)的简写形式,当然,这两个复合注解都还包含其他的注解方法,不过我们现在只需要知道这一些就足够了,然后我们运行服务器,刷新swagger界面会发现我们的新请求就自动的出现在了这上面!

这就是swagger为我们带来的其中一个好处,实时更新,集成以后它会自动的去扫描我们的 Api,然后自动的更新文档,不需要我们再辛苦的手动写一份告诉前端某个接口是干什么的,这个接口需要哪些参数等等,swagger自动的为我们实现了这些,而我们只需要配置一下就好了

swagger常用注解

首先我们需要知道的是swagger是侵入式的框架,但是比起它能带给我们的便利性,这点小小的瑕疵还是可以接受的。swagger 常用的注解有@ApiOperation,@ApiImplicitParam,@Api这三个,@Api一般放在控制器上面,用于分组,@ApiOperation一般放在方法上面用于描述改接口的作用,@ApiImplicitParam通过名称可以知道是用于参数控制的,用来描述需要的参数和对其做一定的限定,比如:

@Api(tags = "用于 Api分组")
@RestController
public class HomeController {

    @ApiOperation(value = "用于描述这个接口是干什么的")
    @GetMapping("/index")
    String index() {
        return "hello world";
    }

    @ApiOperation(value = "通过用户 ID获取用户名")
    @GetMapping(value = "/user/{id}")
    @ApiImplicitParam(name = "id", value = "用户id")
    String findUserByID(@PathVariable Long id) {
        return "小明";
    }

    @ApiOperation(value = "通过用户名,班级获取用户")
    @GetMapping(value = "/user", params = {"username", "classname"})
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用户名", required = false),
            @ApiImplicitParam(name = "classname", value = "班级名", required = false)
    })
    String findUserBy(String username, String classname) {
        return "小明";
    }
  
}

效果是这样的:

这个样子比起之间就更加的简单明了了,而且我们还可以直接在这这里测试接口,可以非常方便的对我们的 Api进行调试,到此,我们在 Spring Boot 中集成swagger差不多就完成了,当然,这里列举出来的东西仅仅是一些基础的使用,不过对于日常的文档编写应该还是足够的,还有一些进阶的使用方法会在以后的使用是慢慢记录出来。

更早的文章

Spring Boot学习记录(一)

前言由于公司业务需要,自己也有学习后台开发的兴趣爱好,所以从今年开始的时候自己慢慢的会学习一些后台相关的知识,主要就是学习 Spring Boot,该系列的教程一个是为了记录自己在学习过程中踩得坑,一个是对自己在学习中的知识整理,如果能帮到更多的人就更好了,下面,开始自己的学习之旅吧工具环境 开发 IDE:IDEA 2019 运行环境:Java1.8 系统: MacOS 10.14.4Helloworld国际惯例,我们开始写一个helloworld工程(笑),主要有两种创建工程的方法...…

java继续阅读