springboot 使用swagger自动生成API文档

如今微服务是趋势,微服务下的web开发通常采用前后端分离的方式.前后端通过API进行交互,Swagger ui,可以生成能让前端开发人员预览且测试的API文档

在SpringBoot中集成swagger,方法如下

  1. 将下面的依赖添加到Maven项目的pom.xml文件中。springfox-swagger2组件帮助我们自动生成描述API的json文件,而springfox-swagger-ui组件就是将这个json文件解析出来,用一种更友好的方式呈现出来。
1
2
3
4
5
6
7
8
9
10
11
<!-- swagger 相关依赖  -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
  1. 添加Swaager2的配置类

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    package com.jetlee.demo1_server.config;

    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;


    @Configuration
    public class Swagger2 {
    @Bean
    public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
    .apiInfo(apiInfo())
    .select()
    .apis(RequestHandlerSelectors.basePackage("com.jetlee.demo1_server"))
    .paths(PathSelectors.any())
    .build();
    }
    private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
    .title("springboot利用swagger构建api文档")
    .description("简单优雅的restfun风格")
    .termsOfServiceUrl("https://www.lijinpeng.top")
    .version("1.0")
    .build();
    }
    }
  2. 在Applocation入口中使用Swagger2 @EnableSwagger2

1
2
3
4
5
6
7
8
9
10
11
12
13
14
package com.jetlee.demo1_server;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class Demo1ServerApplication {

public static void main(String[] args) {
SpringApplication.run(Demo1ServerApplication.class, args);
}
}
  1. 在Controller类上添加@API注解,方法想添加@ApiOperation,以及@ApiImplicitParam参数信息
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    package com.jetlee.demo1_server.controller;

    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiImplicitParam;
    import io.swagger.annotations.ApiOperation;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.PostMapping;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RestController;


    @RestController
    @Api("测试 swagger2")
    public class IndexController {

    @ApiOperation(value = "获取用户列表",notes = "获取用户列表")
    @GetMapping("/getUserList")
    public String getUserList(){
    return "ok";
    }

    @ApiOperation(value = "按id查找用户",notes = "按id查找用户")
    @ApiImplicitParam(name="userId",value="用户id",paramType="query",required = true,dataType = "int")
    @GetMapping("/getUserById")
    public String getUserById(){
    return "user";
    }
    }

这样就可以生成api文档,在浏览器输入http://127.0.0.1:9091/swagger-ui.html显示结果如下
image.png

李金鹏 wechat
ex. subscribe to my blog by scanning my public wechat account
努力工作,好好赚钱