Spring Boot集成springfox-swagger2构建restful API的方法教程

77 阅读 0 评论 51 点赞

我是靠谱客的博主痴情香水，最近开发中收集的这篇文章主要介绍Spring Boot集成springfox-swagger2构建restful API的方法教程，觉得挺不错的，现在分享给大家，希望可以做个参考。

概述

本文在此地址基础上进行swagger构建restful api 的相关补充：
https://www.jb51.net/article/116092.html
https://blog.csdn.net/a807557328/article/details/87192719
然后注意几个关键点信息。

/**
 * com.xxx.web.config.SwaggerConfig.java
 * Copyright 2018 Lifangyu, Inc. All rights reserved.
 */
package com.xxx.configs;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Conditional;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Desc:swagger api 的配置
 * <p>
 * 访问:http://ip:port/swagger-ui.html
 * [localhsot:8081/swagger-ui.html 可能有登录拦截,需要先登录系统后在访问该地址]
 * </p>
 * <p>
 * Created by lifangyu on 2018/3/19.
 */
@Conditional(SwaggerCondition.class)
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * /api.* [访问的路径匹配,如:SwaggerApiController.java @RequestMapping("/api/v1") 符合该路径匹配]
     *
     * @return
     */
    @Bean
    public Docket userApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()// 选择那些路径和api会生成document
                .apis(RequestHandlerSelectors.any()) // //对所有@Api注解进行监控并生成API文档，
//                .paths(PathSelectors.any()) // 对所有路径进行监控[指定匹配路径监控(PathSelectors.regex("/api.*"))]
                .build();
    }

    /**
     * 确保以下配置的信息可用，否则不能访问
     *
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("****-**系统接口文档")
                .description("**-server系统接口文档")
                .license("Apache license")
                .version("2.0")
                .build();
    }
}

附：swagger 生成API文档的注释


@Api：用在类上，说明该类的作用。(开发日常常用)

@ApiOperation：注解来给API增加方法说明。(开发日常常用)

@ApiImplicitParams : 用在方法上包含一组参数说明。

@ApiImplicitParam：用来注解来给方法入参增加说明。

@ApiResponses：用于表示一组响应

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

    1.code：数字，例如400

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

    3.response：抛出异常的类   

@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）

@ApiModelProperty：描述一个model的属性,用于实体类属性(开发日常常用)

注意：@ApiImplicitParam的参数说明：
    1.paramType：指定参数放在哪个地方
    2.header：请求参数放置于Request Header，使用@RequestHeader获取
    3.query：请求参数放置于请求地址，使用@RequestParam获取
    4.path：（用于restful接口）-->请求参数的获取：@PathVariable
    5.body：（不常用）
    6.form（不常用）
    7.name：参数名 
    8.dataType：参数类型
    9.required：参数是否必须传 true | false
    10.value：说明参数的意思 
    11.defaultValue：参数的默认值