spring boot : 集成swagger2 (REST详细设计文档)

       <dependency>

           <groupId>io.springfox</groupId>

           <artifactId>springfox-swagger2</artifactId>

           <version>2.6.1</version>

       </dependency>

       <dependency>

           <groupId>io.springfox</groupId>

           <artifactId>springfox-swagger-ui</artifactId>

           <version>2.6.1</version>

       </dependency>

package com.svw.tbox.tcloud.user.provider;

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.service.Contact;

import springfox.documentation.spi.DocumentationType;

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

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration

@EnableSwagger2

publicclass Swagger2 {

    /**

     * 通过createRestApi函数创建Docket的Bean之后，

     * apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。

     * select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，

     * 本例采用指定扫描的包路径来定义，

     * Swagger会扫描该包下所有Controller定义的API，

     * 并产生文档内容（除了被@ApiIgnore指定的请求）。

     *

     * @return

     */

    @Bean

    public Docket createRestApi() {

        returnnew Docket(DocumentationType.SWAGGER_2)

                .apiInfo(apiInfo())

                .select()

                .apis(RequestHandlerSelectors.basePackage("com.svw.tbox.tcloud.user.provider.controller"))

                .paths(PathSelectors.any())

                .build();

    }

    /**

     * 用来创建该Api的基本信息（这些基本信息会展现在文档页面中）

     *

     * @return

     */

    private ApiInfo apiInfo() {

        returnnew ApiInfoBuilder()

                .title("micro SERVICE RESTful-APIs")

                .description("Restful-API文档,POST添加,GET获取,PUT修改,DELETE删除")

//                .termsOfServiceUrl("http://localhost:8000/swagger-ui.html") //请求swagger-ui.html

                .contact(new Contact("developers","", "[email protected]"))

                .version("1.0")

                .build();

    }

}

package com.svw.tbox.tcloud.user.provider.controller;

import org.apache.commons.lang.StringUtils;

import org.slf4j.Logger;

import org.slf4j.LoggerFactory;

import org.springframework.beans.factory.annotation.Autowired;

import org.springframework.web.bind.annotation.PathVariable;

import org.springframework.web.bind.annotation.RequestMapping;

import org.springframework.web.bind.annotation.RequestMethod;

import org.springframework.web.bind.annotation.RestController;

import com.svw.tbox.tcloud.common.rule.RuleManager;

import com.svw.tbox.tcloud.common.vo.PageRequest;

import com.svw.tbox.tcloud.common.web.Result;

import com.svw.tbox.tcloud.user.provider.entity.UserEntity;

import com.svw.tbox.tcloud.user.provider.rule.AccountRule;

import com.svw.tbox.tcloud.user.provider.service.UserService;

import com.svw.tbox.tcloud.user.provider.vo.UserVO;

import io.swagger.annotations.Api;

import io.swagger.annotations.ApiImplicitParam;

import io.swagger.annotations.ApiImplicitParams;

import io.swagger.annotations.ApiOperation;

/**

 *

 * @author hurf

 *

 * Swagger2默认将所有的Controller中的RequestMapping方法都会暴露，使用注解@ApiIgnore隐藏方法；

 */

@RestController

@Api(description= "用户服务接口")

publicclass UserController {

    privatefinal Logger log = LoggerFactory.getLogger(this.getClass());

    @Autowired

    UserService userService;

    /**

     *  注解@ApiOperation、@ApiImplicitParams、@ApiImplicitParam为API说明；

     *  paramType:查询参数类型 ,query:直接跟参数完成自动映射赋值; path以地址的形式提交数据;

     *  body:流形式提交（POST）;header:参数在request headers 里边提交;form:以form表单的形式提交仅支持POST

     *  @PathVariable获得请求url中的动态参数

     */

    @ApiOperation(value = "新增用户")

    @ApiImplicitParams({ @ApiImplicitParam(name = "userName", value = "用户名", paramType = "query", required = true),

            @ApiImplicitParam(name = "age", value = "年龄（岁）", paramType = "query", required = true),

            @ApiImplicitParam(name = "sex", value = "性别：（1-男 0-女）", paramType = "query", required = true),

            @ApiImplicitParam(name = "grade", value = "级别：（1~10）", paramType = "query", required = true) })

    @RequestMapping(value = "/users", method = RequestMethod.POST)

    public Result add(String userName, intage, intsex, String grade) {

        UserEntity userEntity = new UserEntity();

        userEntity.setName(userName);

        userEntity.setAge(age);

        userEntity.setSex(age == 1 ? true : false);

        userEntity.setGrade(grade);

        return Result.ok(userService.add(userEntity));

    }

    @ApiOperation("根据id单个查询用户")

    @ApiImplicitParam(name = "id", value = "用户id", paramType = "path", required = true)

    @RequestMapping(value = "/users/{id}", method = RequestMethod.GET)

    public Result findUserById(@PathVariable("id") Long id) {

        return Result.ok(userService.getUserById(id));

    }

    @ApiOperation("修改用户")

    @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用户id", paramType = "path", required = true),

            @ApiImplicitParam(name = "userName", value = "用户名", paramType = "query", required = true),

            @ApiImplicitParam(name = "age", value = "年龄（岁）", paramType = "query", required = true),

            @ApiImplicitParam(name = "sex", value = "性别：（1-男 0-女）", paramType = "query", required = true),

            @ApiImplicitParam(name = "grade", value = "级别：（1~10）", paramType = "query", required = true) })

    @RequestMapping(value = "/users/{id}", method = RequestMethod.PUT)

    public Result findUserByName(@PathVariable("id") Long id, String userName, intage, intsex, String grade) {

        UserVO userVO = new UserVO();

        userVO.setId(id);

        userVO.setName(userName);

        userVO.setAge(age);

        userVO.setGrade(grade);

        return Result.ok(userService.updateUser(userVO));

    }

    @ApiOperation(value = "根据用户id删除用户")

    @ApiImplicitParam(name = "id", value = "用户id", paramType = "path", required = true)

    @RequestMapping(value = "/users/{id}", method = RequestMethod.DELETE)

    public Result delUser(@PathVariable("id") Long id) {

        return Result.ok(userService.delUser(id));

    }

    @ApiOperation(value = "根据年龄查用户列表")

    @ApiImplicitParams({ @ApiImplicitParam(name = "age", value = "年龄", paramType = "path", required = true),

            @ApiImplicitParam(name = "pageNo", value = "当前页", paramType = "query", required = true),

            @ApiImplicitParam(name = "pageSize", value = "每页记录数", paramType = "query", required = true) })

    @RequestMapping(value = "/users/getByAge/{age}", method = RequestMethod.GET)

    public Result findUsers(@PathVariable("age") intage, intpageNo, intpageSize) {

        PageRequest page = new PageRequest(pageNo, pageSize);

        return Result.ok(userService.getUsersByAge(age, page));

    }

    /**

     *  访问路径：/users/getByName/hrf?pageNo=1&pageSize=10

     */

    @ApiOperation(value = "根据名称模糊查用户列表")

    @ApiImplicitParams({ @ApiImplicitParam(name = "name", value = "姓名", paramType = "path", required = true),

            @ApiImplicitParam(name = "pageNo", value = "当前页", paramType = "query", required = true),

            @ApiImplicitParam(name = "pageSize", value = "每页记录数", paramType = "query", required = true) })

    @RequestMapping(value = "/users/getByName/{name}", method = RequestMethod.GET)

    public Result findUsers(@PathVariable("name") String name, intpageNo, intpageSize) {

        RuleManager.invalidIf(StringUtils.isBlank(name),AccountRule.NOT_NULL_USERNAME);

        log.info("info根据用户名称{}查询用列表", name);

        log.debug("debug根据用户名称{}查询用列表", name);

        PageRequest page = new PageRequest(pageNo, pageSize);

        return Result.ok(userService.getUserByName(name, page));

    }

}

·        @Api：用在类上，说明该类的作用

·        @ApiOperation：用在方法上，说明方法的作用

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

·        @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

·        paramType：参数放在哪个地方

·        header-->请求参数的获取：@RequestHeader

·        query-->请求参数的获取：@RequestParam

·        path（用于restful接口）-->请求参数的获取：@PathVariable

·        body（不常用）

·        form（不常用）

·        name：参数名

·        dataType：参数类型

·        required：参数是否必须传

·        value：参数的意思

·        defaultValue：参数的默认值

·        @ApiResponses：用于表示一组响应

·        @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

·        code：数字，例如400

·        message：信息，例如"请求参数没填好"

·        response：抛出异常的类

·        @ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）

·        @ApiModelProperty：描述一个model的属性

其他注解参考：https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel