SpringBoot+Swagger2

1.xml文件中添加Swagger2的maven依赖

 

      io.springfox
      springfox-swagger2
      2.7.0


 
      io.springfox
      springfox-swagger-ui
      2.7.0

2.添加Swagger配置类，并使用@EnableSwagger2开启Swagger2

/**
 * Swagger2API文档的配置
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {

    /**
     * Swagger APi接口的配置信息；
     *  @param
     * @return Docket对象
     */
    @Bean
    public Docket createRestApi() {
        //token共同参数的配置
        ParameterBuilder ticketPar = new ParameterBuilder();
        List pars = new ArrayList();  
        ticketPar.name("Authorization").description("TokenValue")
        .modelRef(new ModelRef("string")).parameterType("header") 
        .required(false).build(); 
        pars.add(ticketPar.build());    
        
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .tags(getTags()[0], getTags())
            .select()
            .apis( RequestHandlerSelectors.basePackage("com.syy.test"))
            .paths(PathSelectors.any())
            .build()
            //全局的参数设置
            .globalOperationParameters(pars);
    }

    /**
     * Swagger api的分组信息
     * 
     * @param
     * @return Tag[] 分组数组
     */
    private Tag[] getTags() {
        Tag[] tags =
            {
                new Tag("CM0001_02","分类名称")
                };
        return tags;
    }

    /**
     * Swagger api的描述信息
     * 
     * @param
     * @return ApiInfo对象
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title( "api.info.title")
            .description("api.info.description")
            .contact(new Contact("test", "", ""))
            .version("1.0")
            .build();
    }
    

}

3.创建实体类和Controller

注意实体类名称默认小写开头，大写会丢失注解。
解决：实体类小写命名

@Data
@ApiModel(value = "类名")
public class AS1001_01_001_BO {

    @ApiModelProperty(value = "当前页码", required = true)
    private Integer page = 0;
    
    @ApiModelProperty(value = "每页的条数", required = true)
    private Integer pageSize = 0;
    
    @ApiModelProperty(value = "隐藏测试", hidden = true)
    private Integer test = 0;

}

@RestController
@Api(value = "APP启动-广告页面", tags = { "CM0001_02" })
public class CM0001_01_0001_Controller {
	@Autowired
	private CM0001_01_001_Service cM0001_01_001_Service;

     //body传参
	@ApiOperation(value = "apis说明", notes = "备注")
	@RequestMapping(value = "user/advertise",method = RequestMethod.POST)
	public ResponseResult getResponseResult( @RequestBodyBO @ApiParam(name="bo",value="传参bo",required=true) bo) {
		return ResponseResult.success(cM0001_01_001_Service.getPublicityPageInfo(bo));
	}

    //params传参
	@ApiOperation(value = "apis说明", notes = "备注")
	@ApiImplicitParams({
	       @ApiImplicitParam(name="groupId",value="参数种类ID",required=true,paramType="query"),
	       @ApiImplicitParam(name="parameterId",value="参数ID",required=true,paramType="query")
	   })
	   @RequestMapping(value = "/user/getParameterValue", method = RequestMethod.GET)
	   public ResponseResult getParameterValue( String groupId, String parameterId){
	       String value=commonParameterService.getParameter(groupId, parameterId);
	       return ResponseResult.success(value);
	   }

     //路径类传参
	@ApiOperation(value = "apis说明", notes = "备注")
    @ApiImplicitParams({
        @ApiImplicitParam(name="frameNo",value="车架号",required=true,paramType="path")
    })
    @RequestMapping(value = "/carScan/{frameNo}", method = RequestMethod.GET)
    public ResponseResult getCarInfo(@PathVariable(name="frameNo",required=true) String      frameNo) {
        HM0001_01_001_VO hm0001_01_001_VO = hm0001_04_001_Service.getCarInfo(frameNo);
        return ResponseResult.success(hm0001_01_001_VO);
    }

4.启动Spring Boot项目，访问http://localhost:8080/swagger-ui.html

**

关于Swagger的注解，这里介绍一下

**

@Api：用在请求的类上，表示对类的说明
tags=“说明该类的作用，可以在UI界面上看到的注解”
value=“该参数没什么意义，在UI界面上也看到，所以不需要配置”

示例：@Api(tags=“用户Controller”)

@ApiOperation：用在请求的方法上，说明方法的用途、作用
value=“说明方法的用途、作用”
notes=“方法的备注说明”

示例：@ApiOperation(value=“用户注册”,notes=“手机号、密码都是必输项，年龄随边填，但必须是数字”)

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）–> 请求参数的获取：@PathVariable
· body（不常用）
· form（不常用）
dataType：参数类型，默认String，其它值dataType=“Integer”
defaultValue：参数的默认值

@ApiModel：用于响应类上，表示一个返回响应数据的信息(这种一般用在post创建的时候，使用@RequestBody这样的场景，
请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：用在属性上，描述响应类的属性