swagger：restful管理專案API工具

1、引入最新版本的swagger依賴，低版本的有一些bug。如hidden註解的欄位不生效

        <!-- swagger-mvc -->
        <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>
        <dependency>
            <groupId>org.mapstruct</groupId>
            <artifactId>mapstruct</artifactId>
            <version>1.1.0.Final</version>
        </dependency>
        <!-- swagger-mvc -->
 

2、在spring-mvc.xml中宣告swagger配置bean

<bean class="springfox.documentation.swagger2.configuration.Swagger2DocumentationConfiguration" id="swagger2Config"/>

也可以自定義swagger2Config配置替代上面的配置

<bean class="com.example.liuyaohua.core.config.Swagger2Config" id="swagger2Config"/>

自定義配置對應的java類

@Configuration
@EnableSwagger2
public class Swagger2Config extends WebMvcConfigurationSupport {
    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.liuyaohua.controller.swagger"))
                //.paths(regex("/product.*"))
                .build();
    }
}
 

com.example.liuyaohua.controller.swagger為指定swagger管理的包路徑，如果指定了在頁面中僅顯示該包路徑下的conrtorller入口

3、在spring-mvc.xml中配置資原始檔

	<mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"/>
	<mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>

4、controller樣例及說明

The latest release also adds a number of annotations for adding extensions and metadata at the Swagger Definition level:

示例1：

@Api(description = "日誌相關")
@Controller
@RequestMapping("/log")
public class LogController {

	@Autowired
	private ILogDAO mapper;

	@ApiOperation(value = "查詢記錄(GET)", notes = "查詢記錄:http method is get", httpMethod = "GET", produces = MediaType.APPLICATION_JSON_VALUE)
	@RequestMapping(value = "/user/queryByGet.json",method = RequestMethod.GET)
	@ResponseBody
	public APIResponse<List<Log>> queryByGet(
			@ApiParam(required = true, hidden = false, value = "使用者名稱") @PathVariable String name,
			@ApiParam(required = true, hidden = false, value = "刪除標識",example = "true",allowableValues = "true|false") @PathVariable boolean flag,
			@ApiParam(required = true, value = "當前頁",allowableValues = "1,100",example = "5") @RequestParam("currentPage") int currentPage,
			@ApiParam(required = true, value = "每頁顯示數量") @RequestParam("pageSize") int pageSize) {
		Page page = new Page();
		page.setLow((currentPage - 1) * pageSize);
		page.setHight(currentPage * pageSize);
		page.setUsername(name);
		List<Log> logs = mapper.selectUserLogByPage(page);

		return APIResponse.returnSuccess(logs);
	}

	@ApiOperation(value = "查詢記錄(POST)", notes = "查詢記錄:http method is post", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
	@RequestMapping(value = "/user/queryByPost.json",method = RequestMethod.POST)
	@ResponseBody
	public APIResponse<List<Log>> queryByPost(
			@ApiParam(required = true, hidden = false, value = "使用者名稱") @PathVariable String name,
			@ApiParam(required = true, hidden = false, value = "刪除標識",example = "true",allowableValues = "true|false") @PathVariable boolean flag,
			@ApiParam(required = true, value = "當前頁",allowableValues = "1,5",example = "5") @RequestParam("currentPage") int currentPage,
			@ApiParam(required = true, value = "每頁顯示數量") @RequestParam("pageSize") int pageSize) {
		Page page = new Page();
		page.setLow((currentPage - 1) * pageSize);
		page.setHight(currentPage * pageSize);
		page.setUsername(name);
		List<Log> logs = mapper.selectUserLogByPage(page);

		return APIResponse.returnSuccess(logs);
	}
}

示例2：

@Api(description = "使用者資訊2")
@Controller("userController2")
@RequestMapping("/user2")
public class UserController2 {

    @Resource
    private IUserDAO iUserDAO;

    @Resource
    private ILogDAO iLogDAO;

    private Logger logger = LoggerFactory.getLogger(UserController2.class);

    @ApiOperation(value = "查詢使用者(GET)", notes = "查詢使用者詳細資訊", httpMethod = "GET", produces = MediaType.APPLICATION_JSON_VALUE)
    @RequestMapping(value = "/user/queryByGet.json", params = "name", method = RequestMethod.GET)
    @ResponseBody
    public APIResponse<User> queryByGet(
            @RequestParam(required = true) String name) {
        System.out.println("param name:" + name);
        User user = null;
        try {
            user = iUserDAO.selectUser(name);
            return APIResponse.returnSuccess(user);
        } catch (Exception e) {
            logger.info("查詢使用者失敗", e);
            e.printStackTrace();
            return APIResponse.returnFail("查詢使用者失敗");
        }
    }

    @ApiOperation(value = "新增使用者(POST)", notes = "新增使用者詳細資訊", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
    @RequestMapping(value = "/addByPost", method = RequestMethod.POST)
    @ResponseBody
    public APIResponse<Integer> addByPost(
            @RequestBody User user,
            HttpServletResponse response) {
        try {
            iUserDAO.addUser(user);
            // 記錄日誌
            Log logger = new Log();
            logger.setUserId(user.getId());
            logger.setType(LogTypeEnum.create_user);
            logger.setContent("create user:" + user.getName());
            logger.setCreatetime(new Date());
            iLogDAO.insertLog(logger);

            return APIResponse.returnSuccess(user.getId());
        } catch (Exception e) {
            e.printStackTrace();
            logger.info("新增使用者失敗", e);
            return APIResponse.returnFail("新增使用者失敗");
        }
    }
}

User傳入或返回引數說明樣例：

@ApiModel(value = "userInfo", description = "使用者資訊")
public class User {
    @ApiModelProperty(value = "id", required = true, example = "1000", allowableValues = "1,100")
    private int id;
    @ApiModelProperty(value = "使用者名稱", required = true, example = "張三")
    private String name;
    @ApiModelProperty(value = "生日", required = true, example = "日期")
    private Date birth;
    @ApiModelProperty(value = "使用者狀態", required = true, example = "0", allowableValues = "0,2")
    private UserStatusEnum status;
    @ApiModelProperty(value = "使用者狀態", required = false, example = "true", allowableValues = "true|false")
    private boolean testFlag2;


    @ApiModelProperty(value = "使用者狀態", hidden = true)
    private int flag = 0;

    public int getId() {
        return id;
    }

    @Override
    public String toString() {
        return "User [id=" + id + ", name=" + name + ", birth=" + birth
                + ", status=" + status + "]";
    }

    public void setId(int id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    @JsonSerialize(using = JsonDateSerializer.class)
    public Date getBirth() {
        return birth;
    }

    @JsonDeserialize(using = JsonDateDeserializer.class)
    public void setBirth(Date birth) {
        this.birth = birth;
    }

    public UserStatusEnum getStatus() {
        return status;
    }

    public void setStatus(UserStatusEnum status) {
        this.status = status;
    }

    public int getFlag() {
        return flag;
    }

    public void setFlag(int flag) {
        this.flag = flag;
    }

    public boolean isTestFlag2() {
        return testFlag2;
    }

    public void setTestFlag2(boolean testFlag2) {
        this.testFlag2 = testFlag2;
    }
}

5、通過以上配置啟動專案在瀏覽器中訪問下面地址

localhost:8080/swagger-ui.html

裡面的詳細描述如下

參考：

本文已同步更新到公眾號，溝通交流請關注公眾號。