Swagger 教程

   转自   Vojtech Ruzicka的编程博客

 

(一)Swagger和SpringFox

   记录REST API很是重要。它是一个公共接口，其余模块，应用程序或开发人员可使用它。即便你没有公开曝光它，它仍然很重要。后端和前端代码一般由不一样的开发人员处理。建立API的人一般不是消费它的人。所以，拥有适当记录的界面以免混淆并使其始终保持最新是相当重要的。

最受欢迎的API文档规范之一是OpenApi，之前称为Swagger。它容许您使用JSON或YAML元数据描述API的属性。它还提供了一个Web UI，它能够将元数据转换为一个很好的HTML文档。此外，经过该UI，您不只能够浏览有关API端点的信息，还能够将UI用做REST客户端 - 您能够调用任何端点，指定要发送的数据并检查响应。它很是方便。

然而，手动编写此类文档并在代码更改时保持更新是不现实的。这就是SpringFox发挥做用的地方。它是Spring Framework的Swagger集成。它能够自动检查您的类，检测控制器，它们的方法，它们使用的模型类以及它们映射到的URL。没有任何手写文档，只需检查应用程序中的类，它就能够生成大量有关API的信息。多么酷啊？最重要的是，每当您进行更改时，它们都会反映在文档中。

 

(二)开始项目

首先，你须要一个带有一些Rest Controller的Spring Boot应用程序，我在这里准备了一个简单的。

在本文中，我使用了SpringFox 2.9.2和Spring Boot 1.5.10.RELEASE。它使用Swagger规范的第2版。版本3已经发布，但还没有（截至2014年2月）SpringFox支持。支持应在下一版本中提供。

使用本博文中描述的全部功能构建的最终项目的源代码可在GitHub上得到。

 

(三)添加依赖项

      要在项目中使用SpringFox，您须要先将其添加为依赖项。若是您使用的是Maven，则可使用如下内容（您能够检查是否有更新的版本）。

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

或者若是您使用的是Gradle：

compile "io.springfox:springfox-swagger2:2.9.2"

 

(四)基本配置

添加依赖项后，您须要提供一些基本的Spring配置。虽然您能够在技术上使用现有配置文件之一，但最好为其配置单独的文件。您须要提供的第一件事是@ EnableSwagger2注释。而后你须要提供一个Docket bean，它是用于配置SpringFox的主bean。

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

固然，您能够提供更多配置设置，咱们稍后会看到，但这是一个简约配置，它执行如下操做：

• @ EnableSwagger2支持Swagger 2的SpringFox支持。
• DocumentationType.SWAGGER_2告诉Docket bean咱们正在使用Swagger规范的版本2。
• select（）建立一个构建器，用于定义哪些控制器及其生成的文档中应包含哪些方法。
• apis（）定义要包含的类（控制器和模型类）。这里咱们包括全部这些，但您能够经过基础包，类注释等来限制它们。
• paths（）容许您根据路径映射定义应包含哪一个控制器的方法。咱们如今包括全部这些，但您可使用正则表达式等限制它。

 

(五)添加UI

若是您如今部署应用程序，则已经生成了描述API的swagger元数据！你能够看看：

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

事实证实它只是一个很大的JSON，而不是人类可读的。但你已经能够验证它是否有效。只需转到Swagger在线编辑器并将JSON粘贴到那里。将生成的JSON粘贴到左侧面板，瞧！您如今能够将生成的文档视为HTML页面。不错，不是吗？将这些文档做为应用程序的一部分直接使用会更好。幸运的是，实现这一点很是容易。显示基于JSON输入的HTML文档的GUI称为swagger-ui。要启用它是一个Spring Boot应用程序，您只须要添加此依赖项：

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

//GRADLE 
compile "io.springfox:springfox-swagger-ui:2.9.2"

该文档将在此处自动提供：

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

 

 

(六)添加ApiInfo

默认状况下，咱们文档的标题部分看起来很是通用：

如今是时候作点什么了。咱们能够经过简单的配置更改来更改那里的全部信息。在SpringFoxConfiguration文件中，咱们须要添加ApiInfo对象，该对象提供有关API的通常信息，例如标题，版本，联系人或许可信息。

@Bean
public Docket apiDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.any())
            .build()
            .apiInfo(getApiInfo());
}

private ApiInfo getApiInfo() {
    return new ApiInfo(
            "TITLE",
            "DESCIPRION",
            "VERSION",
            "TERMS OF SERVICE URL",
            new Contact("NAME","URL","EMAIL"),
            "LICENSE",
            "LICENSE URL",
            Collections.emptyList()
    );
}

如今咱们的文档标题应该看起来更好：

(七)缩小已处理的API

到如今为止还挺好。可是当你仔细看看生成的文档时，你会发现除了咱们使用的模型和控制器类以外，还有一些特定于Spring的类，如Controllers部分中的BasicErrorController以及View和ModelAndView下的型号部分。

有时，缩小类，SpringFox会将其检测为文档生成源。Controller和Model类。您能够在Docket配置中轻松配置它。还记得像咱们使用.apis（RequestHandlerSelectors.any（）来包含全部类吗？让咱们将它缩小到咱们的基础包：

 

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

当您想要指定应包含哪些类时，这很是有用。有时您还须要只包含特定的URL路径。您可能正在使用API​​的多个版本以实现向后兼容，但不但愿包含历史版本。也许API的某些部分是内部的，不该该是公共文档的一部分。不管哪一种方式，也能够在Docket中配置基于URL匹配的这种包含。记住.paths（PathSelectors.any（））？您能够将其限制为某些正则表达式或Ant样式的路径模式，而不是匹配全部路径的任何路径。

@Bean
public Docket apiDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.vojtechruzicka"))
            .paths(PathSelectors.ant("/v2/**"))
            .build()
            .apiInfo(getApiInfo());
}

 

若是内置选项对您来讲还不够，您能够随时为apis（）和paths（）提供本身的谓词。忽略某些类或方法的另外一种方法是使用@ApiIgnore注释它们。

(八)使用JSR-303注解

JSR 303：Bean Validation  容许您注释Java类的字段以声明约束和验证规则。您可使用如下规则注释单个字段： - 不能为空，最小值，最大值，正则表达式匹配等。

public class Person {
    @NotNull
    private int id;

    @NotBlank
    @Size(min = 1, max = 20)
    private String firstName;

    @NotBlank
    @Pattern(regexp ="[SOME REGULAR EXPRESSION]")
    private String lastName;

    @Min(0)
    @Max(100)
    private int age;

    //... Constructor, getters, setters, ...
}

这是一种已经普遍使用的常见作法。好消息是，SpringFox能够根据这些注释生成Swagger文档，所以您能够利用项目中已有的内容而无需手动编写全部约束！它很是有用，由于您的API的消费者知道他们应该为您的API提供的值的限制以及指望的值。若是没有包含这样的注释，咱们的人员模型的生成文档看起来很简单，除了字段名称及其数据类型以外什么也没有。

 

使用来自JSR-303注释的数据，它看起来会更好：

 

不幸的是，基于JSR-303的文档没法开箱即用，您须要一个额外的依赖：

//MAVEN
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-bean-validators</artifactId>
   <version>2.9.2</version>
</dependency>

//GRADLE
compile "io.springfox:springfox-bean-validators:2.9.2"

而且您须要在swagger配置类之上导入BeanValidatorPluginsConfiguration配置文件：

@Configuration
@EnableSwagger2
@Import(BeanValidatorPluginsConfiguration.class)
public class SpringFoxConfig {
  ...
}

(九)将Swagger Core注释添加到模型类中

 

使用JSR-303的优势是，若是您已经使用它们，您能够绝不费力地得到额外的文档信息，而无需更改任何代码。问题是目前，SpringFox不显示注释中指定的验证消息。此外，您可能须要记录一些更复杂的约束。在这种状况下，您可使用Swagger Core注释，它容许您指定其余信息，例如描述。用这些注释注释的Person类能够看起来像这样。

 

@ApiModel(description = "Class representing a person tracked by the application.")
public class Person {
    @ApiModelProperty(notes = "Unique identifier of the person. No two persons can have the same id.", example = "1", required = true, position = 0)
    private int id;
    @ApiModelProperty(notes = "First name of the person.", example = "John", required = true, position = 1)
    private String firstName;
    @ApiModelProperty(notes = "Last name of the person.", example = "Doe", required = true, position = 2)
    private String lastName;
    @ApiModelProperty(notes = "Age of the person. Non-negative integer", example = "42", position = 3)
    private int age;

    // … Constructor, getters, setters, ...
}

在类级别，您使用@ApiModel注释并在字段级别@ApiModelProperty。固然，您能够与JSR-303注释混合搭配。 @ApiModelProperty的示例对于提供示例值很是有用，这不只适用于用户的指导，并且还能够在使用Swagger UI做为REST客户端来测试服务时预填充请求有效负载。Position属性很方便指定属性在文档中显示的顺序。首先提供重要或必需的属性或属于一块儿的组属性是有用的。不然，属性将按字母顺序列出。

 

(十)将Swagger Core注释添加到控制器类

与使用Swagger核心注释注释模型类以提供其余元数据相同，您能够注释控制器及其方法和方法参数。

• @Api描述了整个控制器
• @ApiOperation用于方法级别的描述
• @ApiParam用于方法参数

 

@RestController
@RequestMapping("/v2/persons/")
@Api(description = "Set of endpoints for Creating, Retrieving, Updating and Deleting of Persons.")
public class PersonController {

    private PersonService personService;

    @RequestMapping(method = RequestMethod.GET, produces = "application/json")
    @ApiOperation("Returns list of all Persons in the system.")
    public List getAllPersons() {
        return personService.getAllPersons();
    }

    @RequestMapping(method = RequestMethod.GET, path = "/{id}", produces = "application/json")
    @ApiOperation("Returns a specific person by their identifier. 404 if does not exist.")
    public Person getPersonById(@ApiParam("Id of the person to be obtained. Cannot be empty.")
                                    @PathVariable int id) {
        return personService.getPersonById(id);
    }

    @RequestMapping(method = RequestMethod.DELETE, path = "/{id}")
    @ApiOperation("Deletes a person from the system. 404 if the person's identifier is not found.")
    public void deletePerson(@ApiParam("Id of the person to be deleted. Cannot be empty.")
                                 @PathVariable int id) {
        personService.deletePerson(id);
    }

    @RequestMapping(method = RequestMethod.POST, produces = "application/json")
    @ApiOperation("Creates a new person.")
    public Person createPerson(@ApiParam("Person information for a new person to be created.")
                                   @RequestBody Person person) {
        return personService.createPerson(person);
    }

    @Autowired
    public void setPersonService(PersonService personService) {
        this.personService = personService;
    }
}

如今您的文档还应包含所提供的描述：

 

 

请注意，咱们的控制器和域类如今受到Swagger特定注释的困扰。可读性受到很大影响，由于重要的信息在大量的漏洞中丢失了。更糟糕的是 - 当您更改代码时，以这种方式编写的文档不会更新，您须要记住手动更改消息。这会增长您的文档不一样步的风险，所以不值得信任。最好包括一些不明显的基本信息，而这些信息还没有被自动生成的信息很好地涵盖。具备参数的描述性名称以及JSR-303注释一般能够记录大部分所需信息。

 

 

(十一)从属性文件加载描述

直接在注释中提供描述并非很优雅。它可能占用大量空间，污染您的代码。你不能真正支持多种语言。若是要修复拼写错误或对文档进行一些更改，则须要从新构建并从新部署整个应用程序。根据环境，您不能拥有不一样的值。不是很灵活。幸运的是，Spring提供了Property占位符的概念。简而言之，它容许您提供占位符$ {placeholder}而不是硬编码值。而后在.properties文件中定义占位符的值。Spring从属性加载数据并注入它而不是占位符。很酷的是，您能够为每种语言提供多个属性文件。您能够在不一样的环境中提供不一样的属性文件。

SpringFox在一些注释中支持这种机制。这是一种很好的方法，能够将文档与代码分离，并具备更大的灵活性。不幸的是，目前只支持一些注释。所以，例如在模型中，它们在方法级别（@ApiModelProperty）上支持它，但在类级别（@ApiModel）上不支持它。

要完成这项工做，您须要：

1. 建立属性文件，例如swagger.properties
2. 输入您想要的消息做为键值对，其中键将用做占位符 - 例如person.id =此人的惟一标识符
3. 而不是注释文本插入占位符 - 例如$ {person.id}
4. 在类级别注册配置中的属性文件 - 例如。 @PropertySource（ “类路径：swagger.properties”）

 

 

结论

SpringFox是一个有用的工具，它能够根据您的Spring控制器和模型类自动生成Swagger文档。它还能够识别JSR-303注释，所以您还要记录模型类的全部约束。它还可使用核心的swagger类，例如@ApiModelProperty。但要当心，由于这会使你的代码充满了大量特定的注释。只有在SpringFox没法推断信息自己时才使用它们老是更好。仅在须要添加某些描述时才使用它们，其中类，属性和方法名称不能自我解释。再说一遍，你的API多是一个红色标志，说明你的API是神秘的仍是太复杂了。若是您保留由SpringFox自动生成的大部分文档，您能够确保它始终是最新的。除此之外，在代码中进行更改时，您须要很是当心地更新Core Swagger注释。若是您的文档和代码不匹配，用户将失去对您的API文档的信任，而且此类文档几乎无用。

 

 

------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

 

声明： 本文转自      Vojtech Ruzicka的编程博客