Springboot整合swagger2.8.0 在线API文档

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。用处：

1.自动生成在线文档

2.接口测试

整合过程

添加swagger2依赖

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

创建swagger配置类

/**
 * Swaggers 配置
 */
@Configuration
//启用swagger,生产环境请注释掉
@EnableSwagger2
public class Swaggers {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enableUrlTemplating(true)
                .select()
                // 扫描所有有注解的api，用这种方式更灵活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 首页描述
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("更多Spring Boot相关文章请百度：http://www.baidu.com")
                .termsOfServiceUrl("http://www.baidu.com/")
                .build();
    }
}
           

@Configuration注解，让Spring来加载该类配置。再通过@EnableSwagger2注解启用Swagger2

在线文档添加

@RestController
@RequestMapping(value = "/users")
@Api(value = "用户测试信息", tags = {"用户测试相关接口"})//swagger控制器说明注解
public class UserController {
     /**
     * * 入参是对象,使用默认参数paramType = "body"
     * ApiIgnore()用于类，方法，方法参数
     * 表示这个方法或者类被忽略,不被显示在swagger页面上
     * @param resp
     * @param id
     * @param user
     * @return
     */
    @ApiOperation(value = "更新用户详细信息", notes = "根据url的id来指定更新对象，并根据传过来的user信息来更新用户详细信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
    })
    @RequestMapping(value = "/{id}", method = RequestMethod.PUT)
    public String putUser(@ApiIgnore ApiReturnInfo resp,@PathVariable Long id, @RequestBody User user) {
        User u = users.get(id);
        u.setName(user.getName());
        u.setAge(user.getAge());
        users.put(id, u);
        return "success";
    }

}
           

添加swagger注解之后，启动springboot服务，访问浏览器http://localhost:8080/swagger-ui.html 就可以看到在线的API文档。

swaggerUI访问404解决

重新指定静态资源，把swagger-ui.html页面加入

@Configuration
public class ServletContextConfig extends WebMvcConfigurationSupport {
    /**
     * 重新指定静态资源
     * @param registry
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**")
                .addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }

}
           

使用体会

感觉在线文档生成倒是很好用，但swagger自带的接口测试不怎么好用，需要注意很多，

1、在接收参数的地方需要使用@RequestBody，才能接收，这点需要注意下；使用过springboot的同学都清楚，接收参数不需要加注解，就能接收。

2、如果存在多个参数类型，自定义对象及基础类型，这种数据即使使用@RequestBody，后台也是接收失败。目前还没找到解决方案，暂时只使用swagger2的在线文档，调试还是使用postman，汗颜…. ps:有解决方案的小伙伴请留言，不胜感激

完整demo请参考:springboot-swagger2-demo

swagger常用注解说明

• @Api()用于类；

  表示标识这个类是swagger的资源

• @ApiOperation()用于方法；

  表示一个http请求的操作

• @ApiParam()用于方法，参数，字段说明；

  表示对参数的添加元数据（说明或是否必填等）

• @ApiModel()用于类

  表示对类进行说明，用于参数用实体类接收

• @ApiModelProperty()用于方法，字段

  表示对model属性的说明或者数据操作更改

• @ApiIgnore()用于类，方法，方法参数

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

• @ApiImplicitParam() 用于方法

  表示单独的请求参数

• @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam