(一)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>
(四)基本配置
添加依赖项后，您需要提供一些基本的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>
该文档将在此处自动提供：
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(
"标题测试",
"描述测试",
"版本测试",
"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.example.demo4"))
.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类的字段以声明约束和验证规则。您可以使用以下规则注释单个字段： - 不能为空，最小值，最大值，正则表达式匹配等。（Hibernate Validator是在Bean Validation基础上实现了扩展）
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的文档无法开箱即用，您需要一个额外的依赖：
//MAVEN
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-bean-validators</artifactId>
<version>2.9.2</version>
</dependency>
并且您需要在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）上不支持它。
要完成这项工作，您需要：
创建属性文件，例如swagger.properties
输入您想要的消息作为键值对，其中键将用作占位符 - 例如person.id =此人的唯一标识符
而不是注释文本插入占位符 - 例如$ {person.id}
在类级别注册配置中的属性文件 - 例如。 @PropertySource（ “类路径：swagger.properties”）
(十二) securitySchemes的使用
swagger是一个很牛B的东东，但正常使用时，我们的接口需要登陆才能访问的。即登陆时，要传一个登陆后的token才能访问的。
那这个怎么设置，才可以让所有接口都允许登陆后访问呢。
@Configuration
@EnableWebMvc
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket platformApi() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).forCodeGeneration(true)
.select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.apis(RequestHandlerSelectors.any())
.paths(regex("^.*(?<!error)$"))
.build()
.securitySchemes(securitySchemes())
.securityContexts(securityContexts());
}
private List<ApiKey> securitySchemes() {
List<ApiKey> apiKeyList= new ArrayList();
apiKeyList.add(new ApiKey("x-auth-token", "x-auth-token", "header"));
return apiKeyList;
}
private List<SecurityContext> securityContexts() {
List<SecurityContext> securityContexts=new ArrayList<>();
securityContexts.add(
SecurityContext.builder()
.securityReferences(defaultAuth())
.forPaths(PathSelectors.regex("^(?!auth).*$"))
.build());
return securityContexts;
}
List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
List<SecurityReference> securityReferences=new ArrayList<>();
securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
return securityReferences;
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("starmark-API").description("©2018 Copyright. Powered By starmark.")
// .termsOfServiceUrl("")
.contact(new Contact("Starmark", "", "947618@163.com")).license("Apache License Version 2.0")
.licenseUrl("https://github.com/springfox/springfox/blob/master/LICENSE").version("2.0").build();
}
}
- 通过Swagger2的securitySchemes配置全局参数
- 在Swagger2的securityContexts中通过正则表达式，设置需要使用参数的接口（或者说，是去除掉不需要使用参数的接口）
- 设置完成后进入SwaggerUI，右上角出现“Authorization”按钮，点击即可输入我们配置的参数。
对于不需要输入参数的接口（上文所述的包含auth的接口），在未输入Authorization参数就可以访问。
其他接口则将返回401错误。点击右上角“Authorization”按钮，输入配置的参数后即可访问。参数输入后全局有效，无需每个接口单独输入。
(十三) globalResponseMessage的使用
默认的各种状态码的信息如下：
如果想要自己定义，可以使用注解方式，可以单独为一个API配置Response Model
@ApiResponses({
@ApiResponse(code = 400, message = "业务逻辑异常"),
@ApiResponse(code = 407, message = "XX异常"),
@ApiResponse(code = 500, message = "服务器内部错误")
})
public String test(@ApiParam("参数不能为空") @RequestBody User user){
return user.toString();
}
这样做的缺点显而易见，每个Controller上都会有一大堆的、重复的@ApiResponses注解，以至于把正常的业务代码淹没。
可以在全局设置：
@Bean
public Docket userApi() {
List<ResponseMessage> responseMessageList = new ArrayList<>();
responseMessageList.add(new ResponseMessageBuilder().code(404).message("找不到资源").responseModel(new ModelRef("ApiError")).build());
responseMessageList.add(new ResponseMessageBuilder().code(409).message("业务逻辑异常").responseModel(new ModelRef("ApiError")).build());
responseMessageList.add(new ResponseMessageBuilder().code(422).message("参数校验异常").responseModel(new ModelRef("ApiError")).build());
responseMessageList.add(new ResponseMessageBuilder().code(500).message("服务器内部错误").responseModel(new ModelRef("ApiError")).build());
responseMessageList.add(new ResponseMessageBuilder().code(503).message("Hystrix异常").responseModel(new ModelRef("ApiError")).build());
return new Docket(DocumentationType.SWAGGER_2)
.globalResponseMessage(RequestMethod.GET, responseMessageList)
.globalResponseMessage(RequestMethod.POST, responseMessageList)
.globalResponseMessage(RequestMethod.PUT, responseMessageList)
.globalResponseMessage(RequestMethod.DELETE, responseMessageList)
.build()
.apiInfo(apiInfo());
}
结论
SpringFox是一个有用的工具，它可以根据您的Spring控制器和模型类自动生成Swagger文档。它还可以识别JSR-303注释，因此您还要记录模型类的所有约束。它还可以使用核心的swagger类，例如@ApiModelProperty。但要小心，因为这会使你的代码充满了大量特定的注释。只有在SpringFox无法推断信息本身时才使用它们总是更好。仅在需要添加某些描述时才使用它们，其中类，属性和方法名称不能自我解释。再说一遍，你的API可能是一个红色标志，说明你的API是神秘的还是太复杂了。如果您保留由SpringFox自动生成的大部分文档，您可以确保它始终是最新的。除此以外，在代码中进行更改时，您需要非常小心地更新Core Swagger注释。如果您的文档和代码不匹配，用户将失去对您的API文档的信任，并且此类文档几乎无用。
