SpringBoot中使用Swagger生成RESTful规范API文档

版权声明：本文为博主原创文章，未经博主允许不得转载。 https://blog.csdn.net/a78270528/article/details/78506338

Swagger是为了描述一套标准的而且是和语言无关的REST API的规范。对于外部调用者来说，只需通过Swagger文档即可清楚Server端提供的服务，而不需去阅读源码或接口文档说明。

官方网站为：http://swagger.io
中文网站：http://www.sosoapi.com

背景
前后端分离
1、前后端仅仅通过异步接口(AJAX/JSON)来编程
2、前后端都各自有自己的开发流程，构建工具，测试集合
3、关注点分离，前后端变得相对独立并松耦合

 

 

开发流程
1、后台编写和维护接口文档，在 API 变化时更新接口文档
2、后台根据接口文档进行接口开发
3、前端根据接口文档进行开发
4、开发完成后联调和提交测试

 

 

三大功能
1、Swagger Editor: Swagger提供的一个编辑器，用来通过Swagger提供的特定的YAML语法来编写API文档
2、Swagger Codegen: 代码生成器
3、Swagger UI: YAML语法定义我们的RESTful API，然后它会自动生成一篇排版优美的API文档，并且提供实时预览。

面临问题
1、没有统一的文档编写规范，导致文档越来越乱，无法维护和阅读。
2、开发中的接口增删改等变动，需要较大的沟通成本。
3、对于一个新需求，前端开发的接口调用和自测依赖后台开发完毕。
4、将接口的风险后置，耽误项目时间。

 

 

解决方法
1、接口文档服务器 -- 解决接口文档编辑和维护的问题。
2、mock 数据 -- 解决前端开发依赖真实后台接口的问题。

 

 

一、接口文档服务器：
1、修改pom.xml，添加maven依赖

3. io.springfox

4. springfox-swagger2

5. 2.6.1

7.  
8.  

10. io.springfox

11. springfox-swagger-ui

12. 2.6.1

2、添加Swagger配置类，Swagger会默认把所有Controller中的RequestMapping方法都生成API出来，实际上我们一般只需要标准接口的（像返回页面的那种Controller方法我们并不需要），所有你可以按下面的方法来设定要生成API的方法的要求。 
如下我针对RestController注解的类和ResponseBody注解的方法才生成Swaager的API，并且排除了特定的类，代码如下：

1. import org.springframework.context.annotation.Bean;

2. import org.springframework.context.annotation.Configuration;

3. import springfox.documentation.builders.ApiInfoBuilder;

4. import springfox.documentation.builders.PathSelectors;

5. import springfox.documentation.builders.RequestHandlerSelectors;

6. import springfox.documentation.service.ApiInfo;

7. import springfox.documentation.spi.DocumentationType;

8. import springfox.documentation.spring.web.plugins.Docket;

9. import springfox.documentation.swagger2.annotations.EnableSwagger2;

10. import springfox.documentation.service.Tag;

11.  
12.  

13. @Configuration

14. @EnableSwagger2

15. public class Swagger2Config {

16.  
17.  

18. @Bean

19. public Docket createRestApi() {

20. return new Docket(DocumentationType.SWAGGER_2)

21. .apiInfo(apiInfo())

22. .select()

23. .apis(RequestHandlerSelectors.basePackage("com.bocom.gzxf.jcsj.controller"))

24. .paths(PathSelectors.any())

25. .build();

26. }

27.  

28. private ApiInfo apiInfo() {

29. return new ApiInfoBuilder()

30. .title("实战指挥平台--基础数据API说明文档")

31. .description("2017.11.9上线版本")

32. //.termsOfServiceUrl("http://mindao.com.cn")

33. .contact("智慧消防研发部")

34. .version("1.0")

35. .build();

36. }

37. }

3、对外接口类配置

1. /**

2. * Controller

3. *

4. * @since 2017年9月8日上午9:39:32

5. * @author shanming.yang

6. *

7. */

8. @RestController

9. @RequestMapping("/user")

10. @Validated

11. @Api(value = "USER", description = "测试UserController")

12. public class UserController {

13. private static Logger logger = LogManager.getLogger(UserController.class.getName());

14. @Resource

15. private DemoService demoService;

16.  
17.  

18. @RequestMapping(value="",method={RequestMethod.GET })

19. @ApiOperation(value = "查询个人信息接口",notes = "查询个人信息接口")

20. @ApiImplicitParams({

21. @ApiImplicitParam(paramType = "header", dataType="string", name = "token", value = "访问凭证", required = true),

22. })

23. public List query(@RequestParam("page") int page,

24. @RequestParam("count") int count) {

25. return demoService.query(page, count);

26. }

27.  

28. @RequestMapping(value="",method={RequestMethod.POST })

29. @ApiOperation(value = "增加个人信息接口",notes = "增加个人信息接口")

30. public void insert(@RequestAttribute("name") String name) {

31. Demo model = new Demo();

32. String uuid = UUID.randomUUID().toString().replaceAll("-", "");

33. model.setId(uuid);

34. model.setAge("25");

35. model.setName(name);

36. demoService.insert(model);

37. }

38. }

 

经过这3步配置后，我们启动服务后，访问：http://localhost:8080/swagger-ui.html 就完成了集成。

Swagger2默认将所有的Controller中的RequestMapping方法都会暴露，然而在实际开发中，我们并不一定需要把所有API都提现在文档中查看，这种情况下，使用注解@ApiIgnore来解决，如果应用在Controller范围上，则当前Controller中的所有方法都会被忽略，如果应用在方法上，则对应用的方法忽略暴露API。

 

4、相关注解解读

1. @Api
用在类上，说明该类的作用
@Api(value = "UserController", description = "用户相关api")

2. @ApiOperation
用在方法上，说明方法的作用
@ApiOperation(value = "查找用户", notes = "查找用户", httpMethod = "GET", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)

3 @ApiImplicitParams
用在方法上包含一组参数说明

4. @ApiImplicitParam
用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
paramType：参数放在哪个地方
header–>请求参数的获取：@RequestHeader
query–>请求参数的获取：@RequestParam
path（用于restful接口）–>请求参数的获取：@PathVariable
body（不常用）
form（不常用）
name：参数名
dataType：参数类型
required：参数是否必须传
value：参数的意思
defaultValue：参数的默认值
@ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "唯一id", required = true, dataType = "Long", paramType = "path"),
})
5. @ApiResponses
用于表示一组响应

6. @ApiResponse
用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如”请求参数没填好”
response：抛出异常的类
@ApiResponses(value = {  
          @ApiResponse(code = 400, message = "No Name Provided")  
  })
7. @ApiModel
描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModel(value = "用户实体类")

8. @ApiModelProperty
描述一个model的属性
@ApiModelProperty(value = "登录用户")

Swagger接口请求有几个：
http://localhost:8080/swagger-resources/configuration/ui
http://localhost:8080/swagger-resources
http://localhost:8080/api-docs
http://localhost:8080/swagger-resources/configuration/security

 

附：使用Swagger生成JAVA Mock Server（Springboot）代码
http://blog.csdn.net/a78270528/article/details/78530702