使用Swagger2构建Spring Boot RESTful AIP 文档

澳门新浦京8455com 7

本文由码农网 –
Pansanday原创翻译,转发请看清文末的转载要求,款待参加大家的付费投稿陈设澳门新浦京8455com,!

    上一篇大家介绍了何等运用Spring Boot快捷创设RESTful API “Spring
Boot与RESTful API”
,本篇则介绍三个同盟Spring Boot迅速营造RESTful文书档案的工具

写在前头

利用RESTful
API作为Web服务对外提供劳动的输入,基本上已经化为了行业内部,在提供REST
API的同期,如何开展
API文书档案管理是八个相比麻烦的事情,作为开采职员大家都打听API文书档案的器重,但老是嫌其编写的劳动,Swagger的
现身很好地帮我们缓和文书档案编写的事务,开辟人士能够使用协和爱怜的姿势举行API文书档案编写,比方利用Swagger-Editor
拓宽API的提前安排,进而使用Swagger-Codegen来扭转二种语言的顾客端代码,使用Swagger-UI来进展API文书档案
的直观查看,当然你也足以在代码中一向开展API文书档案的编写,本课程将介绍怎样在Spring
REST API项目中,举行
Swagger2的合一,那样便足以很便利地实行API文书档案编写了。

在本篇教程司令员选取Springfox的Swagger完毕来集成,关于 Swagger2 和
Springfox 的牵线如下:

  • Swagger 2
  • Springfox

在上一篇文章中,小编提及了使用Spring Boot创建RESTFul劳动的资历。当创立三个REST
API的时候,合适的文书档案是很主要的一部分。

    由于Spring Boot具有高效支付、便捷布置的表征,非常多客户会采纳Spring
Boot营造RESTful
API,叁个RESTful接口往往对应不断贰个终端,有WEB端、安卓端、IOS端等等。正因为这么,一个接口或许要面临八个开采职员也许组织,为了减小调换到带的时刻花销,我们往往会希图一个RESTful
API的文书档案,可是这种文书档案往往有多少个沉重的难点:

项目构造

本学科将假诺你早就有了叁个Spring
REST服务,若无话,能够参照Spring官方项目示范:

Building a RESTful Web
Service

Swagger是什么

Swagger(Swagger 2)是陈述和记录REST
API的三个规范。它钦定了REST
Web服务的格式,包罗U福特ExplorerL,能源,方法等。Swagger将从应用程序代码生成文书档案,并拍卖渲染部分。

在此篇小说中,作者会将Swagger 2文书档案集成到基于Spring Boot的REST
Web服务中。笔者将运用Springfox兑现来生成swagger文书档案。如果您想明白是什么样运作/创设Spring
Boot项指标,请参见我上一篇随笔。

Springfox提供了多个依靠关系来生成API文书档案和Swagger
UI。如若您不期望将Swagger UI集成到你的API中,则无需增加Swagger
UI注重关系。

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger2</artifactId>

<version>2.7.0</version>

</dependency>

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

<version>2.7.0</version>

</dependency>

@
EnableSwagger2批注启用了Springfox
Swagger在类中的支持。为了记录这些服务,Springfox使用了三个Docket类。Docket有利于配置要记录的劳务,并透过名称等实行分组。后台是Springfox通过运用基于Spring配置的API语义,在运维时检查应用程序。换句话说,你一定要成立二个使用Spring的@Configuration表明的Spring
Java Configuration类。

在本身的例证中,作者会生成一个基于自个儿加多的RestController类的swagger文书档案。

import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class ApplicationConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.chandana.helloworld.controllers"))
                .paths(PathSelectors.any())
                .build();
    }
}

是因为笔者增添了三个调节器,因而将分头对种种调节器相关的API进行分组(标志)。

澳门新浦京8455com 1

开箱即用,Springfox提供了5种断言,它们各自是any,none,withClassAnnotation,withMethodAnnotation和basePackage【译者注:参见springfox.documentation.builders. RequestHandlerSelectors类】

  1. 鉴于接口过多,细节复杂,文书档案本人创设起来就相比较费心
  2. 趁着年华的延期,接口往往会纠正可能放弃,那就需求对富有调用方同步文书档案,若是出现疏漏,超级轻易形成接口调用退步

添加Maven依赖

在你的Spring REST项目中加多maven注重,张开项指标pom.xml,增多如下内容:

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

ApiInfo

Swagger提供了有的暗中认可值,举例“API文书档案”,“通过联系人电子邮件创立”,“Apache
2.0”。当然你能够通过增多apiInfo(ApiInfo
apiInfo)方法来改造这么些私下认可值。ApiInfo类满含关于API的自定义音讯。

@Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.chandana.helloworld.controllers"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo getApiInfo() {
        Contact contact = new Contact("Chandana Napagoda", "http://blog.napagoda.com", "cnapagoda@gmail.com");
        return new ApiInfoBuilder()
                .title("Example Api Title")
                .description("Example Api Definition")
                .version("1.0.0")
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                .contact(contact)
                .build();
    }

要是增添了ApiInfo,生成的文书档案看起来就如那样:

澳门新浦京8455com 2

    为了缓和上述难题,就要介绍一下Swagger2,它可以很简短的结缘到Spring
Boot中,它能够团体出强大的RESTful API文书档案。效果如图:

在档期的顺序中集成Swagger2

Controller和POJO层文档

@Api申明用于表明每种调控器类(有一些像类注释)。

@ApiOperation注脚用于描述财富和方式。

@ApiResponse申明用于证明操作重返的别样响应值。举例:200
ok或202 accepted等

@ApiModelProperty申明用来陈述POJO(Bean)类的属性(属性描述)。

增进上述注释后,最后生成的swagger文书档案如下所示:

澳门新浦京8455com 3

Spring RestController类:

package com.chandana.helloworld.controllers;

import com.chandana.helloworld.bean.Greeting;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
@Api(value = "user", description = "Rest API for user operations", tags = "User API")
public class HelloWorldController {

    @RequestMapping(value = "/hello/{name}", method = RequestMethod.GET, produces = "application/json")
    @ApiOperation(value = "Display greeting message to non-admin user", response = Greeting.class)
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "OK"),
            @ApiResponse(code = 404, message = "The resource not found")
    }
    )
    public Greeting message(@PathVariable String name) {
        Greeting msg = new Greeting(name, "Hello " + name);
        return msg;
    }
}

Greeting模型类:

package com.chandana.helloworld.bean;

import io.swagger.annotations.ApiModelProperty;

public class Greeting {

    @ApiModelProperty(notes = "Provided user name", required =true)
    private String player;

    @ApiModelProperty(notes = "The system generated greeting message" , readOnly =true)
    private String message;

    public Greeting(String player, String message) {
        this.player = player;
        this.message = message;
    }

    public String getPlayer() {
        return player;
    }

    public void setPlayer(String player) {
        this.player = player;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }
}

AppConfig类:

package com.chandana.helloworld.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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class ApplicationConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.chandana.helloworld.controllers"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo getApiInfo() {
        Contact contact = new Contact("Chandana Napagoda", "http://blog.napagoda.com", "cnapagoda@gmail.com");
        return new ApiInfoBuilder()
                .title("Example Api Title")
                .description("Example Api Definition")
                .version("1.0.0")
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                .contact(contact)
                .build();
    }
}

您也得以从自家的GitHub repo 下载  Swagger Spring Boot
Project 源代码。

译者注:

  1. 假定你对Spring Boot不是很熟悉,提议先fork下源码,因为某些重视文中未有提到。
  2. 初始Spring Boot后,在浏览器中输入:127.0.0.1:8080/swagger-ui.html就可以查看生成的文书档案消息。

在调换的文书档案页面中,能够输入参数,点击“Try it
out!”就能够开展接口测量检验,有一点点相符于Postman的效率。

澳门新浦京8455com 4

集成Swagger2

第一创造三个SwaggerConfiguration类,如下:

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {                                    
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)  
          .select()                                  
          .apis(RequestHandlerSelectors.any())              
          .paths(PathSelectors.any())                          
          .build();                                           
    }
}

通过运用@EnableSwagger2讲解来拉开Swagger2,在任何类中最注重的便是Docket的Bean,Docket定义了
Swagger的版本、需求揭穿的API等信息,大家来看看Docket变迁后都做了些什么职业:

  1. 创制多个Docket对象
  2. 调用select()方法,生成ApiSelectorBuilder对象实例,该对象承受定义外漏的API入口
  3. 通过运用RequestHandlerSelectorsPathSelectors来提供Predicate,在那我们选取any(State of Qatar方法,将持有API都通过Swagger举办理文件书档案管理

若果你的体系是二个Spring
Boot项目,上边的安插已经OK了,能够起始进行API文书档案的编辑了,但借使您的门类
不是Spring Boot项目,只是Spring项目来讲,必要多少多做些工作。

    此番以上篇小说的代码为例对Swagger2进行传授。

非Spring Boot项目中,配置Resource Handler

出于未有利用Spring Boot,那样就无法自动配置Resource
Handler,需求团结开展下布置,因为大家接下去要选用
Swagger
UI,它微微静态财富须求加载,新建叁个类,世袭WebMvcConfigurerAdapter并利用@EnableWebMvc证明,然后增加如下代码,即使您早本来就有了七个这么的类,能够举行将以下代码增添至该类:

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

    registry.addResourceHandler("/webjars/**")
      .addResourceLocations("classpath:/META-INF/resources/webjars/");
}

导入Swagger2依赖

    在pom.xml中增添对Swagger2的注重

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

心得成果

一旦小编是选择Spring REST官方示例项目以来,展开浏览器,输入:

http://localhost:8080/v2/api-docs

你应当会看出JSON格式的API文档,如下图所示:

澳门新浦京8455com 5

Swagger2 API Docs

如此的JSON文件,读起来是非常不低价的,接下去大家用Swagger UI来进展查看。

创建Swagger2类

    Swagger2类要求与Application.java同级

@Configuration
@EnableSwagger2
public class Swagger2 {
    @Bean
    public Docket createRestApi() {
        //需要配置正确需要扫面的的包名
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.wangxin.restapi"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("更多Spring Boot相关文章请关注:https://my.oschina.net/wangxincj/blog/")
                .termsOfServiceUrl("https://my.oschina.net/wangxincj/blog/")
                .contact("老虎是个蛋蛋")
                .version("1.0")
                .build();
    }
}

    如上所示,

  • 增多@Configuration注脚,表示让Spring在运营时加载该配置
  • @EnableSwagger2表示在Spring Boot中启动Swagger2
  • createRestApi方法创制Docket的Bean
  • apiInfo(卡塔尔国用来创制该API的主导消息
  • ApiInfoBuilder实力来决定那一个接口须求暴光给Swagger来展现

Swagger UI

Swagger UI提供了Web页面以造福开荒人士查看API文书档案等。

丰裕文书档案内容表明

   
大家经过行使@ApiOperation评释对接口实行描述,通过@ApiImplicitParam和@ApiImplicitParams对参数进行描述

@RestController
@RequestMapping("/book")
public class BookController {
    public static Map<String,Book> bookMap = new HashMap<String,Book>();

    /**
     * 添加一本书
     * @param book
     * @return
     */
    @ApiOperation(value="创建一本书", notes="创建一本书")
    @ApiImplicitParam(name = "book", value = "book实体bean", required = true, dataType = "Book")
    @RequestMapping(value="",method = RequestMethod.POST)
    public String postBook (@ModelAttribute Book book){
        bookMap.put(book.getIsbn(),book);
        return "SUCCESS";
    }

    /**
     * 查询出所有book集合
     * @return
     */
    @ApiOperation(value="查询出所有book集合", notes="")
    @RequestMapping(value={""},method = RequestMethod.GET)
    public List<Book> getBookList (){
        List<Book> bookList = new ArrayList<Book>(bookMap.values());
        return bookList;
    }

    /**
     * 根据ISBN获取book
     * @param isbn
     * @return
     */
    @ApiOperation(value="图书详细信息", notes="根据url的isbn来获取图书详细信息")
    @ApiImplicitParam(name = "isbn", value = "ISBN", required = true, dataType = "String")
    @RequestMapping(value="/{isbn}",method = RequestMethod.GET)
    public Book getBook(@PathVariable String isbn){
        Book book = bookMap.get(isbn);
        return book;
    }

    /**
     * 更新book参数
     * @param isbn
     * @param book
     * @return
     */
    @ApiOperation(value="更新图书详细信息", notes="根据url的ISBN来指定更新对象,并根据传过来的book信息来更新图书详细信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "isbn", value = "ISBN", required = true, dataType = "String"),
            @ApiImplicitParam(name = "book", value = "图书详细实体book", required = true, dataType = "Book")
    })
    @RequestMapping(value="/{isbn}",method = RequestMethod.PUT)
    public String putBook(@PathVariable String isbn, @ModelAttribute Book book){
        Book b = bookMap.get(isbn);
        b.setAuthor(book.getAuthor());
        b.setName(book.getName());
        bookMap.put(isbn,b);
        return "SUCCESS";
    }

    /**
     * 根据isbn删除book
     * @param isbn
     * @return
     */
    @ApiOperation(value="删除图书", notes="根据url的ISBN来指定删除图书")
    @ApiImplicitParam(name = "isbn", value = "ISBN", required = true, dataType = "String")
    @RequestMapping(value="/{isbn}",method = RequestMethod.DELETE)
    public String deleteBook(@PathVariable String isbn){
        bookMap.remove(isbn);
        return "SUCCESS";
    }
}

    完结上述操作,大家运行Spring
Boot,访谈,就可以看出Swagger2生成的RESTful
API,如下:

澳门新浦京8455com 6

集成Swagger UI

在项目pom.xml中引入:

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

在这里运维示例项目,在浏览器中输入:

http://localhost:8080/swagger-ui.html

能够见见如下Web页面:

澳门新浦京8455com 7

Swagger UI

API调试

    Swagger2不只好够生成API文档,还能在线调节和测量试验接口,如上海体育地方,有两种填写参数方式,第一种是在Parameter列表项中有Book对象需求填写的参数,大家能够依赖真实情状填写参数值;第三种方法我们能够点击上海图书馆中左边的Model
Schema(粉红白区域:它指明了Book的数据构造),那时Value中就有了book对象的模版,我们只必要稍适订正。填写完参数点击“Try
it out!”就可以达成接口央求。

    比较为这么些接口编写文书档案的办事,大家扩充的配备内容是超级少况兼轻便的,对于原本代码的侵入也在经受范围以内。因此,在创设RESTful
API的同一时候,参与swagger来对API文档实行政管理理,是个科学的选料。

  • swagger官网

 

写在背后

到此你已经成功地在类型中融为一炉了Swagger2,接下去能够行使Springfox的批注实行API文书档案编写了,详细阅读:

http://springfox.github.io/springfox/docs/current/

You can leave a response, or trackback from your own site.

Leave a Reply

网站地图xml地图