SpingBoot 集成 Swagger2

Swagger2的Spring Boot Starter 方便配置Swagger2。

https://github.com/kangarooxin/spring-boot-starter-swagger2

使用说明:

1. build and install jar

git clone https://github.com/kangarooxin/spring-boot-starter-swagger2.git
cd spring-boot-starter-swagger2
mvc clean install

2.在pom.xml导入依赖

<dependency>
    <groupId>com.github.kangarooxin</groupId>
    <artifactId>spring-boot-starter-swagger2</artifactId>
    <version>1.0.0</version>
</dependency>

3. 配置properties

   #swagger2
   #swagger2.enabled=true
   swagger2.title=${spring.application.name}
   swagger2.version=1.0.0
   swagger2.contact-name=kangarooxin
   swagger2.contact-email=kangarooxin@github.com
   #扫码目录，支持多目录
   swagger2.base-package=com.example.controller
   #是否包含子目录
   swagger2.include-sub-package=true
   #全局参数配置
   swagger2.global-parameters[0].name=appId
   swagger2.global-parameters[0].description=应用ID
   swagger2.global-parameters[0].required=true
   swagger2.global-parameters[0].model-ref=int
   swagger2.global-parameters[1].name=accessToken
   swagger2.global-parameters[1].description=访问秘钥
   swagger2.global-parameters[1].required=false
   swagger2.global-parameters[1].model-ref=string

4. 支持多group配置

   #group1配置
   swagger2.groups.group1.title=${spring.application.name}
   swagger2.groups.group1.group-name=group1-name
   swagger2.groups.group1.version=1.0.0
   swagger2.groups.group1.base-package=com.example.controller.group1
   #group2配置
   swagger2.groups.group2.title=${spring.application.name}
   swagger2.groups.group2.group-name=group2-name
   swagger2.groups.group2.version=1.0.0
   swagger2.groups.group2.base-package=com.example.controller.group2

5. 使用Swagger2注解API接口

@Slf4j
@RestController
@Validated
@RequestMapping("/api/help")
@Api(tags = "帮助文档接口")
public class HelpController  {
    @Autowired
    private HelpService helpService;

    @ApiOperation("文档列表")
    @RequestMapping(value = "/list", method = RequestMethod.GET)
    public ResponseEntity<List<HelpVo>> list()  {
        return ok(helpService.list());
    }

    @ApiOperation("文档详细列表")
    @RequestMapping(value = "/detail/list", method = RequestMethod.GET)
    public ResponseEntity<List<HelpDetailVo>> listDetailByHelpId(@ApiParam(value = "帮助文档ID", required = true) @RequestParam int helpId) {
        return ok(helpService.listDetailByHelpId(helpId));
    }

}

6. Swagger2常用注解
   • @Api：修饰整个类，描述Controller的作用
   • @ApiOperation：描述一个类的一个方法，或者说一个接口
   • @ApiParam：单个参数描述
   • @ApiModel：用对象来接收参数
   • @ApiProperty：用对象接收参数时，描述对象的一个字段
   • @ApiResponse：HTTP响应其中1个描述
   • @ApiResponses：HTTP响应整体描述
   • @ApiIgnore：使用该注解忽略这个API
   • @ApiError ：发生错误返回的信息
   • @ApiImplicitParam：描述一个请求参数，可以配置参数的中文含义，还可以给参数设置默认值
   • @ApiImplicitParams：描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表
7. 启动应用
   SpringBoot 启动成功后，访问 http://host:port/swagger-ui.html
8. 使用增强版的swagger-bootstrap-ui
   swagger-bootstrap-ui是springfox-swagger的增强UI实现，为Java开发者在使用Swagger的时候，能拥有一份简洁、强大的接口文档体验
   加入依赖：

<dependencies>
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-spring-boot-starter</artifactId>
        <!--在引用时请在maven中央仓库搜索最新版本号-->
        <version>2.0.2</version>
    </dependency>
</dependencies>

添加注解：@EnableKnife4j
访问地址：http://host:port/doc.html