spring boot + swagger2

spring boot集成swagger2:

    swagger2是一个基于restful的开源设计,构建,文档,访问的开源工具集.开发中它的在线可视化文档功能,可以动态生成文档,简化前后对接工作.以下是Java在spring boot中使用方式:    

• 引入maven依赖:

　　springfox-swagger2是swagger核心代码;springfox-swagger-ui提供静态jsUI可视化页面

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

 

• 启用swagger

package com.ssth.exchange.exsite;
 
import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
@SpringBootApplication(scanBasePackages = { "com.ssth.exchange.exsite"})
@Configuration
@MapperScan("com.ssth.exchange.exsite.mapper")
@EnableSwagger2
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

使用@EnableSwagger2注解启用swagger

• 在接口中添加对应注解

package com.ssth.exchange.exsite.controller;
 
import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.CrossOrigin;
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.ResponseBody;
import org.springframework.web.bind.annotation.RestController;
 
import com.ssth.exchange.exsite.controller.basic.ExsiteBaseController;
import com.ssth.exchange.exsite.controller.request.NavigationReq;
import com.ssth.exchange.exsite.controller.response.NavigationResp;
import com.ssth.exchange.exsite.controller.response.ResponseEntity;
import com.ssth.exchange.exsite.service.HomeService;
 
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
 
/**
* @Description 首页控制器
* @author chengmuyu
* @date 2018年5月31日 下午2:31:12
*/
@RestController
@RequestMapping("/home")
@ResponseBody
@CrossOrigin
@Api(value="首页接口",consumes="application/json")
public class HomeController extends ExsiteBaseController {
 
    @Autowired
    private HomeService homeService;
    
    /**
     * @Description 获取导航列表
     * @param nav 导航查询参数
     * @return
     */
    @RequestMapping(value = "list/nav",method = RequestMethod.POST)
    @ApiOperation(value="获取导航列表", httpMethod = "POST", response = NavigationResp.class)
    public ResponseEntity<List<NavigationResp>> listNavigation(@RequestBody NavigationReq nav) {
        return ResponseEntity.successResponse(homeService.listNavigation(nav.getPid()));
    }
}

对应注解说明:

@Api：修饰整个类，value:描述Controller的作用,consumes:声明参数类型

@ApiOperation:修饰请求接口.value:描述接口;httpMethod:接口请求方式;response:定义接口响应实体;

 

 

• 实体声明定义

package com.ssth.exchange.exsite.controller.request;
 
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
 
/**
* @Description 导航请求实体
* @author chengmuyu
* @date 2018年5月31日 下午3:04:05
*/
@ApiModel(value = "导航请求")
public class NavigationReq {
    @ApiModelProperty(value = "导航父id,null表示查询一级目录")
    private String pid;
}

@ApiModel:修饰实体类

@ApiModelProperty:修饰实体参数

 

 

• Swagger常用注解

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。
@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

　　

 

官方示例文档地址:

https://hantsy.gitbooks.io/build-a-restful-app-with-spring-mvc-and-angularjs/content/swagger.html