springboot项目利用Swagger2生成在线接口文档

• Swagger简介。

         Swagger2是一款restful接口文档在线生成和在线调试工具。很多项目团队利用Swagger自动生成接口文档，保证接口文档和代码同步更新、在线调试。简单地说，你可以利用这个工具生成你的接口文档而不是自己去写，而且生成的文档在网站上可以让别人调试。

• 开发环境

     Eclipse+Maven+Swagger2

•   具体步骤

1.      引入Maven依赖。（很多JAVA组件使用的第一步）

     我的maven坐标如下

<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>

这里我的版本是2.7，当然也可以引用其他版本的。

  2.  添加JAVA配置类。用于配置Swagger运行信息。JAVA配置类本质上和SSM项目的XML配置一样，但是比较安全（这一点还有待研究）

package XXX.springboot.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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("XXX.springboot.web"))
.paths(PathSelectors.any())
.build();
}

private ApiInfo apiInfo(){
return new ApiInfoBuilder().title("Spring Boot中使用Swagger生成Restful-Api文档")
.version("1.0").build();
}

}

 这里说明一下：

ApiInfoBuilder().title("Spring Boot中使用Swagger构建Rest Api")   title里面的内容是生成接口文档页面的标题。

RequestHandlerSelectors.basePackage("XXX.springboot.web")     括号里面的内容是你的Contrller接口所在包的路径。
（为什么这么配？？我也不知道.问JAVA大神，他回答：这么配就对了！为什么，框架自动反射（其实他也不知道）！）

3. 最后一步，添加接口注释

@Api(value="/test", tags="产品接口模块")
@RestController
public class CategoryController {

@Autowired CategoryService categoryService;

@ApiOperation(value="展示产品信息", notes = "展示产品信息")
@RequestMapping("/listCategory")
public List<Category> listCategory(Model m) throws Exception {
List<Category> cs=categoryService.listAllCategory();

m.addAttribute("cs", cs);

return cs;
}
}

这里用到了两个注解：

@Api用于类,表示标识这个类是swagger资源。

@ApiOperation用于方法，表示这是一个http请求操作。

swagger还有很多注解，比如@ApiParam，@ApiModel。我还没来得及一一了解。

4.运行springboot程序，在浏览器中访问

我创建的springboot程序就是一个简单的JAVA程序。所以在Eclipse中直接运行就好了。

在浏览器中输入：http://127.0.0.1:8888/swagger-ui.html 进行访问.                    (127.0.0.1是回环地址，我的springboot项目的tomcat服务器端口配置了为8888)