Swagger学习

Swagger

SpringBoot整合Swagger2：

1. 添加swagger-spring-boot-starter依赖

   <dependency>    
       <groupId>com.spring4all</groupId>
       <artifactId>swagger-spring-boot-starter</artifactId》
       <version>1.9.0.RELEASE</version>
   </dependency>
   

2. 应用主类中添加@EnableSwagger2Doc注解

3. application.properties中配置文档相关内容，如：

   swagger.title=spring-boot-starter-swagger
   swagger.description=Starter for swagger 2.x
   swagger.version=1.4.0.RELEASE
   swagger.license=Apache License, Version 2.0
   swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html
   swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger
   swagger.contact.name=didi
   swagger.contact.url=http://blog.didispace.com
   swagger.contact.email=dyc87112@qq.com
   swagger.base-package=com.didispace
   swagger.base-path=/**
   

   各参数配置含义如下：

   • swagger.title：标题
   • swagger.description：描述
   • swagger.version：版本
   • swagger.license：许可证
   • swagger.licenseUrl：许可证URL
   • swagger.termsOfServiceUrl：服务条款URL
   • swagger.contact.name：维护人
   • swagger.contact.url：维护人URL
   • swagger.contact.email：维护人email
   • swagger.base-package：swagger扫描的基础包，默认：全扫描
   • swagger.base-path：需要处理的基础URL规则，默认：/**

4. 启动应用，访问：http://localhost:8080/swagger-ui.html

5. @Api(tags="")，@ApiOperation("value="")注解来给API增加说明、通过@ApiImplicitParam、@ApiModel、@ApiModelProperty注解来给参数增加说明。

Swagger2Markup简介

Swagger2Markup是Github上的一个开源项目。该项目主要用来将Swagger自动生成的文档转换成几种流行的格式以便于静态部署和使用，比如：AsciiDoc、Markdown、Confluence。

使用SpringFox 3生成Swagger文档

1. 添加依赖

   <dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-boot-starter</artifactId>
   <version>3.0.0</version>
   </dependency>
   

2. 应用主类增加注解@EnableOpenApi（上面的方式是用@EnableSwagger2Doc）

3. 其余注解相同

4. 启动应用！访问swagger页面：http://localhost:8081/swagger-ui/index.html

5. 两个可访问路径：http://host/context-path/swagger-ui/index.html和http://host/context-path/swagger-ui/，以前老版本的文档接口/v2/api-docs之外，还多了一个新版本的/v3/api-docs接口。