Swagger2自动生成APi文档

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务的接口文档。

添加依赖：

        <!--Swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <!--Swagger ui-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>

进行创建SwaggerConfig配置

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket docket(){

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder().title("微信支付案例接口文档").build());

    }
}

代码中进行注解使用：

在接口文件中增加对应注解。代码如下，由于我们第二步选择扫描接口的方式是在类前添加@Api；@ApiOperation用于注明接口，value是接口的解释；@ApiParam注解函数里面的参数，name一般与参数名一致，value是解释，required是是否参数必须。

import com.jt.vo.R;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import java.util.Date;

@Api("商品管理")  
@RequestMapping("/api/product")
@RestController
public class ProductController {

    @ApiOperation("测试接口")
    @RequestMapping(value = "/test",method = RequestMethod.GET)
    public R test(@ApiParam(name="name",value="对话人",required=true) String name){

        return R.ok().data("666","测试").data("时间",new Date());
    }
}

注意：在接口中使用了@RequestMapping时，必须指定接口的形式，是get还是post等。否则Swagger会把所有类型都创建。

上面操作都完成后，在浏览器中输入网址：http://localhost:8080/swagger-ui.html

 定义参数内容

  @ApiOperation("新增用户")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "userId", value = "用户id", dataType = "Integer", dataTypeClass = Integer.class),
        @ApiImplicitParam(name = "username", value = "用户名称", dataType = "String", dataTypeClass = String.class),
        @ApiImplicitParam(name = "password", value = "用户密码", dataType = "String", dataTypeClass = String.class),
        @ApiImplicitParam(name = "mobile", value = "用户手机", dataType = "String", dataTypeClass = String.class)
    })
    @PostMapping("/save")
    public R<String> save(UserEntity user)
    {
        if (StringUtils.isNull(user) || StringUtils.isNull(user.getUserId()))
        {
            return R.fail("用户ID不能为空");
        }
        users.put(user.getUserId(), user);
        return R.ok();
    }

 

 

swagger api注解

这一部分除了，下面列出的注解外，还包括上面所介绍的RequestHandlerSelectors和PathSelectors的几种方法及含义。

@Api： 用于类，标识这个类是swagger的资源
@ApiIgnore： 用于类，忽略该 Controller，指不对当前类做扫描
@ApiOperation： 用于方法，描述 Controller类中的 method接口
@ApiParam： 用于参数，单个参数描述，与 @ApiImplicitParam不同的是，他是写在参数左侧的。如（ @ApiParam(name="username",value="用户名")Stringusername）
@ApiModel： 用于类，表示对类进行说明，用于参数用实体类接收
@ApiProperty：用于方法，字段，表示对model属性的说明或者数据操作更改
@ApiImplicitParam： 用于方法，表示单独的请求参数
@ApiImplicitParams： 用于方法，包含多个 @ApiImplicitParam
@ApiResponse： 用于方法，描述单个出参信息
@ApiResponses： 用于方法，包含多个@ApiResponse
@ApiError： 用于方法，接口错误所返回的信息