SpringBoot使用SWAGGER2生成项目在线API文档



一个项目中往往接口文档维护是我们比较头疼的地方,一个接口改动了,文档也要跟着变动,工作量挺大。现在我们来用SpringBoot中的SWAGGER2来自动生成一份漂亮的在线api文档,接口变动也不需要再去维护文档,代码即文档。

1、快速新建一个SpringBoot的工程

    我们使用官网提供的工具来定制生成,访问:http://start.spring.io/点击页面中的Switch to the full version. 根据自己的需要勾选合适自己项目的工具,最后点击Generate Project下载项目。QCv思考者日记网-束洋洋个人博客

2、工程中加入swagger2的jar依赖支持

我们上面下载的项目已经是一个maven的工程了,再pom.xml中加入QCv思考者日记网-束洋洋个人博客

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.2.2</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.2.2</version>
</dependency>

3.编写swagger2设置代码

package cn.com.shuyangyang;

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;

/**
 * @Description Swagger2设置<br />
 * @author shuyangyang<br />
 * @sites <a href="www.shuyangyang.com.cn/">www.shuyangyang.com.cn</a><br />
 * @date 2017年10月19日 上午11:29:30 <br />
 * @version V0.1 <br />
 */
@Configuration
@EnableSwagger2
public class Swagger2 {
	/**
	 * @Description 设置Docket对象中的swagger2需要生成api文档的包目录
	 * @return
	 */
	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
				.apis(RequestHandlerSelectors.basePackage("cn.com.shuyangyang.controller")).paths(PathSelectors.any()).build();
	}

	/**
	 * @Description 设置api文档页面的标题描述
	 * @return
	 */
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder().title("Spring Boot - RESTful APIs")
				.description("更多Spring Boot相关文章请关注:http://www.shuyangyang.com.cn/")
				.termsOfServiceUrl("http://www.shuyangyang.com.cn/").contact("束洋洋").version("1.0").build();
	}
}

 QCv思考者日记网-束洋洋个人博客

4、编写普通的代码演示效果

package cn.com.shuyangyang.controller;

import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import cn.com.shuyangyang.entity.User;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;

@RestController
@RequestMapping("/users")
public class UserController {

	@ApiOperation(value="跳转到用户列表页面", notes="用户分页列表页面")
	@RequestMapping(value={"/toList"}, method=RequestMethod.GET)
	public String toList(){
		return "user List";
	}
	
	@ApiOperation(value="新增用户", notes="保存用户信息")
	@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
	@RequestMapping(value={"/addUser"}, method=RequestMethod.POST)
	public String addUser(@RequestBody User user){
		return "success";
	}
}

 QCv思考者日记网-束洋洋个人博客

注意:这里使用的@ApiOperation@ApiImplicitParam注解用来描述接口的参数、使用等。(我们可以把平时写的注释省略)QCv思考者日记网-束洋洋个人博客

5、启动工程查看效果

第一步生产的代码中有main方法运行的类和容器运行的类,分别为XXApplication.javaServletInitializer.java,我们任选其一运行工程 访问:http://localhost:8080/swagger-ui.html (容器运行需要加工程名)QCv思考者日记网-束洋洋个人博客

在线APIQCv思考者日记网-束洋洋个人博客

展开具体的接口,可以进行调试,cool~QCv思考者日记网-束洋洋个人博客

调试QCv思考者日记网-束洋洋个人博客

 

(转载本站文章请注明作者和出处 思考者日记网|束洋洋个人博客 ,请勿用于任何商业用途)

『访问 思考者日记网404页面 寻找遗失儿童』

告知
  •     本站90%以上文章均属原创,部分转载已加上原作者出处。 如需转载本站文章请您务必保留本站出处!
  •     打广告评论者请自重,请为广大网友提供一个健康干净的网络空间。
  •  感谢主机屋提供网站空间;
  •  感谢万网阿里云提供域名解析;
  •  感谢EmpireCMS提供CMS系统;
  •  感谢bootstrap展示本站前端页面;
  •  感谢Glyphicons Halflings提供字体;
  •  感谢大家一直以来对本站的喜爱,感谢大家!
近期文章 建议与反馈