spring boot2.0整合 swagger2.9

Swagger作用

在前后端分离中，API接口文档的纽带作用显得尤为重要。后端甩给前端一份接口文档，前端就知道传入参数的方法、参数类型、以及返回类型。Swagger的作用就是你不必手写接口文档，并且后端在写完接口后还能用swagger进行测试，可谓一举三得。

**使用springboot 2.0.0 整合 swagger2.9**

1. 新建Springboot项目，并引入swagger依赖

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

两个依赖的作用

springfox-swagger2依然是依赖OSA规范文档，也就是一个描述API的json文件，而这个组件的功能就是帮助我们自动生成这个json文件，
springfox-swagger-ui就是将这个json文件解析出来，用一种更友好的方式呈现出来。

2. 配置Swagger2

在springboot启动类同级目录中创建Swagger2的配置文件

package me.hong.icarus;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 *  swagger2
 *  地址栏输入如下：
 *  http://localhost:9092/swagger-ui.html#
 */
@Configuration
@EnableSwagger2
public class Swagger2 implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/static/**")
                .addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

    @Bean
    public Docket createRestApi() {
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("Rest Api")
                .description("Just once that all I need")
                .termsOfServiceUrl("http://www.icarus.com")
                .contact(new Contact("擎天柱", "", "[email protected]"))
                .version("1.0.0")
                .build();
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("me.hong.icarus"))
                .paths(PathSelectors.any())
                .build();
    }
}

编写Controller

package me.hong.icarus.user.controller;

import com.alibaba.dubbo.config.annotation.Reference;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import me.hong.icarus.user.model.User;
import me.hong.icarus.user.rest.service.UserService;
import org.springframework.cloud.context.config.annotation.RefreshScope;
import org.springframework.web.bind.annotation.*;

@RestController
@RefreshScope
@RequestMapping(value = "/icarus/icarus")
public class UserController {

    @Reference
    UserService userService;

    @ApiOperation(value = "通过id获取用户",httpMethod = "GET")
    @ApiImplicitParams(value = {})
    @GetMapping(value = "/user/get_id/{id}")
    public User getUserById(@PathVariable("id") String id) {
        try {
            return userService.getUserById(id);
        } catch (Exception e) {
            e.printStackTrace();
            throw e;
        }
    }
}

浏览器打开Swagger2API文档

在地址栏输入：http://localhost:9092/swagger-ui.html#。其中9092是项目端口号。

在实际使用中，应该了解关于Swagger2的具体注解的参数说明，这个很基础也很重要。