swagger2使用步驟

本人是springboot集成swagger2的環境。
並且項目中過濾器會對請求進行攔截，因此需要對一下URI放行：

注意：
生產環境是不允許查看swagger的,可以使用@Profile({“dev”, “test”})
詳細禁用方式查看：
https://blog.csdn.net/LiuKingJia/article/details/89878320

 // swagger 相關接口
    String[] includeUrlSwagger = new String[]{"/webjars", "/v2", "/swagger-resources", "/swagger-ui"};
    
    String uri = request.getRequestURI();
    for (String swaggerUrl: includeUrlSwagger) {
            if (uri.contains(swaggerUrl)) {
                isNeedFilter = false;
                break;
            }
     }       
 	if (!needFilter) {
            //不需要過濾直接傳給下一個過濾器
            filterChain.doFilter(requestWrapper != null ? requestWrapper : request, servletResponse);
    }

步驟簡要

pom導入
swagger配置類
controller:
類名上：@Api(description = “系統用戶相關接口”)
方法上：@ApiOperation(“系統註冊登錄接口”)
入參DTO實體類以及成員變量中的實體類：
類名上：@ApiModel(value = “系統用戶”)
變量上：@ApiModelProperty(value = “*審覈狀態”, example = “2”, allowableValues = “2, 3”, required = true)
Result實體類及出參VO實體類：
類名上：@ApiModel(“響應結果”)
變量上：@ApiModelProperty(value = "接口返回狀態碼; ", example = “1”, position = 0)

注意事項

接口的出參入參儘量使用實體類對象，不要使用Map
返回的Result一定要標記泛型，否則生成的接口文檔data是空對象,
如：
public Result submitLogin(UserDTO UserDTO) {}
入參實體類中@ApiModelProperty的required :true或flase時，暫未發現UI界面此配置的展示，因此在value配置中標明，如：
@ApiModelProperty(value = “*人員ID(修改時必填)”, example = “10086”, required = false, position = 1)
@ApiModelProperty(value = “*年份”, example = “2016”, required = true, position = 1)
入參字段描述也在value配置中標明
@ApiModelProperty(value = “接口返回狀態碼;1成功;-1失敗;-2參數異常”, example = “1”, position = 0)
Swagger-UI界面接口參數默認按開頭字母排序，如有需求配置position

1.pom依賴

<!-- swagger -->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.5.0</version>
</dependency>

<!-- swagger-ui -->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.5.0</version>
</dependency>

2.swagger2配置類

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.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @Description: swagger 配置
 */
@Configuration
@EnableSwagger2
@Profile({"dev", "test"})
public class SwaggerConfig {

    /**
     * 創建Rest Api描述
     * @return
     */
    @Bean
    public Docket createRestApi() {
     	List<ResponseMessage> responseMessageList = new ArrayList<>();
        responseMessageList.add(new ResponseMessageBuilder().code(401).message("未經授權")
                .responseModel(new ModelRef("Result")).build());
        responseMessageList.add(new ResponseMessageBuilder().code(404).message("找不到資源")
                .responseModel(new ModelRef("Result")).build());
        responseMessageList.add(new ResponseMessageBuilder().code(500).message("服務器內部錯誤")
                .responseModel(new ModelRef("Result")).build());

        return new Docket(DocumentationType.SWAGGER_2)
        		.globalResponseMessage(RequestMethod.GET, responseMessageList)
                .globalResponseMessage(RequestMethod.POST, responseMessageList)
                .globalResponseMessage(RequestMethod.PUT, responseMessageList)
                .globalResponseMessage(RequestMethod.DELETE, responseMessageList)
                .apiInfo(apiInfo())
                .select()                       //按條件指定生成文檔接口
                .paths(PathSelectors.any())
                .build();
    }
    /**
     * 接口描述
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XXXX項目")
                .description("XXXX模塊")
                .version("1.0")
                .build();
    }
}

3.註解配置
@Api(description = “管理接口”) :作用在類上面，說命名該controller的作用
@ApiOperation(“添加用戶接口”) :作用在方法(具體的接口)上,說明該方法是幹什麼的接口

POST請求：

@Data
@ApiModel(value = "系統用戶", description = "系統用戶對象")
public class UserDTO implements Serializable {
	// 用戶id
	@ApiModelProperty(
	value = "用戶id",
	name = "id",
	example = "3b8f975f932d98a3582d9c629db9",
	required = true)
	@NotNull(message = "用戶id爲空")
	private String id;
}

有參GET請求：

/**
     * 根據系統模塊查詢角色列表
     *
     * @param subSystem
     * @return
     */
    @GetMapping("list/{subSystem}")
    @ApiOperation("根據系統模塊查詢角色列表")
    public Result getRoleListBySystem(
            @ApiParam(
                    value = "系統模塊",
                    allowableValues = "1, 2, 3",
                    example = "1",
                    required = true)
            @PathVariable("subSystem") String subSystem) {
    }

Swagger 通過註解定製接口對外展示的信息，這些信息包括接口名、請求方法、參數、返回信息等。更多註解類型：
•	@Api：修飾整個類，描述Controller的作用
•	@ApiOperation：描述一個類的一個方法，或者說一個接口
•	@ApiParam：單個參數描述
•	@ApiModel：用對象來接收參數
•	@ApiProperty：用對象接收參數時，描述對象的一個字段
•	@ApiResponse：HTTP響應其中1個描述
•	@ApiResponses：HTTP響應整體描述
•	@ApiIgnore：使用該註解忽略這個API
•	@ApiError ：發生錯誤返回的信息
•	@ApiImplicitParam：描述一個請求參數，可以配置參數的中文含義，還可以給參數設置默認值
•	@ApiImplicitParams：描述由多個 @ApiImplicitParam 註解的參數組成的請求參數列表