学完这篇文章，如果你再不懂API文档的话，那你就没有必要学了

API文档

Swagger是用于设计、构建和详细说明RESTful API的最流行的工具。它由SmartBear创建，SmartBear是一个非常流行的SOAP Web服务工具SoapUI的设计者。对于那些具有长期使用SOAP经验的开发人员来说，这可能是一个很好的建议。无论如何，在使用Swagger的情况下，开发人员可以使用表示法设计API，然后从中生成源代码;或者反过来，可以从源代码开始，然后生成Swagger文件。在有了Spring Boot之后，开发人员可以考虑使用第二个选项。

 

联合使用Swagger 2和 Spring Boot

Spring Boot和 Swagger 2之间的集成将由Springfox项目实现。它在运行时会检查应用程序,以基于Spring 配置、类结构和Java注解来推断API语义。要将Swagger 与Spring结合在一起使用，开发人员需要将以下两个依赖项添加到Maven的pom.xml 中，并且使用@EnableSwagger2 注解主应用程序类。

io.springfox
springfox-swagger22.7.0


io.springfox
springfox-swagger-ui2.7.0

在应用程序启动期间，Swagger库将自动从源代码生成API文档。该过程由 Docketbean 控制，该bean也将在主类中声明。这里有一个好主意，那就是从Maven的pom.xml文件中获取API版本。要获取该信息，开发人员可以在类路径中包含maven-model库并使用MavenXpp3Reader类。开发人员还可以使用 apilnfo方法设置其他一些属性,如标题、作者和详细说明等。默认情况下，Swagger 会为所有 REST 服务生成说明文档，包括由Spring Boot 创建的服务。开发人员应该将此说明文档仅放置于 
pl.piomin.services.boot.controller包中的@RestController。

Bean
public Docket api () throws IOException,XmlPullParserException(
MavenXpp3Reader reader - new MavenXpp3Reader(;
Model model = reader.read(new FileReader( "pom. xml"));ApiInfoBuilder builder = new ApiInfoBuilder (
.title("Person Service Api Documentation")
.description ( "Documentation automatically generated"").version (model.getVersion())
.contact(new Contact("Piotr Minkowski"，
"piotrminkowski.wordpress.com","[email protected]") );return new Docket ( DocumentationType.SWAGGER_2).select O
.apis (RequestHandlerSelectors.basePackage ("pl.piomin.services.boot.controller"))
-paths (Pathselectors.any(0).build(.apiInfo(builder.build();

使用 Swagger UI测试API

在应用程序启动之后,即可在 
http://localhost:2222/swagger-ui.html位置看到API说明文档仪表板（Dashboard)，这是Swagger JSON定义文件的一个对用户更友好的版本，并且它也是自动生成的，可从 http://localhost:2222/v2/api-docs获得，如图2.2所示。该文件可以由任何其他REST工具（如SoapUI）导入。

 

如果开发人员更喜欢SoapUI而不是 Swagger UI，则可以通过选择Project | ImportSwagger(项目|导入Swagger）来轻松导入Swagger定义文件。然后，需要提供一个文件地址,如图2.3所示。

 

就个人而言，笔者更喜欢Swagger UI。开发人员可以展开每个API方法以查看其详细信息。可以通过提供所需的参数或JSON输入来测试每个操作，然后单击Try it Out!(试一试!）按钮。如图2.4所示就是发送一个POST /person测试请求的截图。

 

其响应截图如图2.5所示。

 

大家如果需要的话可以扫码下方来获取: