关闭

SpringBoot非官方教程 | 第十一篇:springboot集成swagger2,构建优雅的Restful API

标签: api文档框架测试
31538人阅读 评论(10) 收藏 举报
分类:

转载请标明出处:
http://blog.csdn.net/forezp/article/details/71023536
本文出自方志朋的博客

swagger,中文“拽”的意思。它是一个功能强大的api框架,它的集成非常简单,不仅提供了在线文档的查阅,而且还提供了在线文档的测试。另外swagger很容易构建restful风格的api,简单优雅帅气,正如它的名字。

一、引入依赖

        <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>

二、写配置类

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.forezp.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .description("简单优雅的restfun风格,http://blog.csdn.net/forezp")
                .termsOfServiceUrl("http://blog.csdn.net/forezp")
                .version("1.0")
                .build();
    }
}

通过@Configuration注解,表明它是一个配置类,@EnableSwagger2开启swagger2。apiINfo()配置一些基本的信息。apis()指定扫描的包会生成文档。

三、写生产文档的注解

swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等。

  • @Api:修饰整个类,描述Controller的作用
  • @ApiOperation:描述一个类的一个方法,或者说一个接口
  • @ApiParam:单个参数描述
  • @ApiModel:用对象来接收参数
  • @ApiProperty:用对象接收参数时,描述对象的一个字段
  • @ApiResponse:HTTP响应其中1个描述
  • @ApiResponses:HTTP响应整体描述
  • @ApiIgnore:使用该注解忽略这个API
  • @ApiError :发生错误返回的信息
  • @ApiParamImplicitL:一个请求参数
  • @ApiParamsImplicit 多个请求参数

现在通过一个栗子来说明:

package com.forezp.controller;

import com.forezp.entity.Book;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.ui.ModelMap;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

import java.util.*;

/**
 * 用户创建某本图书 POST    /books/
 * 用户修改对某本图书    PUT /books/:id/
 * 用户删除对某本图书    DELETE  /books/:id/
 * 用户获取所有的图书 GET /books
 *  用户获取某一图书  GET /Books/:id
 * Created by fangzhipeng on 2017/4/17.
 * 官方文档:http://swagger.io/docs/specification/api-host-and-base-path/
 */
@RestController
@RequestMapping(value = "/books")
public class BookContrller {

    Map<Long, Book> books = Collections.synchronizedMap(new HashMap<Long, Book>());

    @ApiOperation(value="获取图书列表", notes="获取图书列表")
    @RequestMapping(value={""}, method= RequestMethod.GET)
    public List<Book> getBook() {
        List<Book> book = new ArrayList<>(books.values());
        return book;
    }

    @ApiOperation(value="创建图书", notes="创建图书")
    @ApiImplicitParam(name = "book", value = "图书详细实体", required = true, dataType = "Book")
    @RequestMapping(value="", method=RequestMethod.POST)
    public String postBook(@RequestBody Book book) {
        books.put(book.getId(), book);
        return "success";
    }
    @ApiOperation(value="获图书细信息", notes="根据url的id来获取详细信息")
    @ApiImplicitParam(name = "id", value = "ID", required = true, dataType = "Long",paramType = "path")
    @RequestMapping(value="/{id}", method=RequestMethod.GET)
    public Book getBook(@PathVariable Long id) {
        return books.get(id);
    }

    @ApiOperation(value="更新信息", notes="根据url的id来指定更新图书信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "图书ID", required = true, dataType = "Long",paramType = "path"),
            @ApiImplicitParam(name = "book", value = "图书实体book", required = true, dataType = "Book")
    })
    @RequestMapping(value="/{id}", method= RequestMethod.PUT)
    public String putUser(@PathVariable Long id, @RequestBody Book book) {
        Book book1 = books.get(id);
        book1.setName(book.getName());
        book1.setPrice(book.getPrice());
        books.put(id, book1);
        return "success";
    }
    @ApiOperation(value="删除图书", notes="根据url的id来指定删除图书")
    @ApiImplicitParam(name = "id", value = "图书ID", required = true, dataType = "Long",paramType = "path")
    @RequestMapping(value="/{id}", method=RequestMethod.DELETE)
    public String deleteUser(@PathVariable Long id) {
        books.remove(id);
        return "success";
    }

    @ApiIgnore//使用该注解忽略这个API
    @RequestMapping(value = "/hi", method = RequestMethod.GET)
    public String  jsonTest() {
        return " hi you!";
    }
}

通过相关注解,就可以让swagger2生成相应的文档。如果你不需要某接口生成文档,只需要在加@ApiIgnore注解即可。需要说明的是,如果请求参数在url上,@ApiImplicitParam 上加paramType = “path” 。

启动工程,访问:http://localhost:8080/swagger-ui.html ,就看到swagger-ui:

Paste_Image.png

整个集成过程非常简单,但是我看了相关的资料,swagger没有做安全方面的防护,可能需要我们自己做相关的工作。

四、参考资料

swagger.io

Spring Boot中使用Swagger2构建强大的RESTful API文档

6
0
查看评论

SpringBoot(七):SpringBoot整合Swagger2

相信各位在公司写API文档数量应该不少,当然如果你还处在自己一个人开发前后台的年代,当我没说,如今为了前后台更好的对接,还是为了以后交接方便,都有要求写API文档。 手写Api文档的几个痛点: 文档需要更新的时候,需要再次发送一份给前端,也就是文档更新交流不及时。接口返回结果不明确不能直接在...
  • saytime
  • saytime
  • 2017-07-10 23:01
  • 7725

Spring Boot 集成Swagger

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单...
  • catoop
  • catoop
  • 2016-02-15 16:02
  • 44462

Spring-Boot + Swagger2 自动生成API接口文档

spring-boot作为当前最为流行的Java web开发脚手架,相信越来越多的开发者会使用其来构建企业级的RESTFul API接口。这些接口不但会服务于传统的web端(b/s),也会服务于移动端。
  • amon1991
  • amon1991
  • 2017-08-06 15:51
  • 1522

SpringBoot集成springfox-swagger2构建restful API

Springboot集成springfox-swagger2构建restful API,Springmvc集成springfox-swagger2构建restful API,
  • u014231523
  • u014231523
  • 2017-01-15 16:28
  • 5587

springboot+swagger2说明

swagger用于定义API文档。 优势: 前后端分离开发API文档非常明确测试的时候不需要再使用URL输入浏览器的方式来访问Controller传统的输入URL的测试方式对于post请求的传参比较麻烦(当然,可以使用postman这样的浏览器插件 添加pom依赖 io.sprin...
  • fanpeng1100
  • fanpeng1100
  • 2017-01-04 10:09
  • 6666

SpringBoot集成Swagger

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单...
  • java_4_ever
  • java_4_ever
  • 2016-05-06 16:54
  • 6805

springboot(六)配置swagger2

springboot swagger
  • u011493599
  • u011493599
  • 2016-12-29 18:23
  • 5334

springboot +swagger2 小例子

  • 2017-11-03 11:17
  • 14.53MB
  • 下载

springboot接入swagger2

因为项目前后端分离了,所以就使用了swagger2来进行前后端的沟通。相当之方便。写这篇博文是防忘记。
  • u014519194
  • u014519194
  • 2017-01-16 10:13
  • 668

Spring Boot + Swagger

前言: 在互联网公司, 微服务的使用者一般分为两种, 客户端和其他后端项目(包括关联微服务),不管是那方对外提供文档 让别人理解接口 都是必不可少的。传统项目中一般使用wiki或者文档, 修改繁琐,调用方不一定及时了解变化。 微服务时代,效率第一,使用Swagger可以在部署的时候生成在线文档,同时...
  • molashaonian
  • molashaonian
  • 2017-06-10 18:27
  • 302
    个人资料
    • 访问:4705478次
    • 积分:15327
    • 等级:
    • 排名:第876名
    • 原创:125篇
    • 转载:1篇
    • 译文:0篇
    • 评论:1720条
    公众号推荐
    加我微信,拉你进Spring Cloud中国社区群



    关注我的微信公众号,优质内容定期分享
    博客专栏
    共同进步
    Spring Cloud中国社区QQ交流群:643970587
    我的邮箱:miles02@163.com
    最新评论