效果圖

在這里插入圖片描述

一：swagger是什么？

1、是一款讓你更好的書寫API檔案的規范且完整框架，

2、提供描述、生產、消費和可視化RESTful Web Service，

3、是由龐大工具集合支撐的形式化規范，這個集合涵蓋了從終端用戶介面、底層代碼庫到商業API管理的方方面面，

二：使用

方法一：使用第三方依賴（最簡單的方法）

1、在pom.xml檔案中添加第三方swagger依賴（）

	<dependency>
		<groupId>com.spring4all</groupId>
		<artifactId>swagger-spring-boot-starter</artifactId>
		<version>1.7.0.RELEASE</version>
	</dependency>

2、在Spring Boot專案的啟動類上添加@EnableSwagger2Doc注解，就可以直接使用啦，
3、https://github.com/SpringForAll/spring-boot-starter-swagger這是GitHub上這個swagger依賴實作的專案，里面有詳細的講解，

方法二：使用官方依賴+配置類

1、在pom.xml檔案中添加swagger相關依賴

        <!--        swagger-->
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

第一個是API獲取的包，第二是官方給出的一個ui界面，這個界面可以自定義，默認是官方的，對于安全問題，以及ui路由設定需要著重思考，
2、swagger的configuration

需要特別注意的是swagger scan base package,這是掃描注解的配置，即你的API介面位置，

package com.bennyrhys.swagger.config;


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

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.bennyrhys.swagger"))
                .paths(PathSelectors.any())
//                基本網站配置資訊
                .build().apiInfo(new ApiInfoBuilder()
                        .description("介面檔案描述資訊")
                        .title("專案介面檔案")
                        .contact(new Contact("bennyrhys", "htpps://xxx", "bennyrhys@163.com"))
//                        .version("v1.0.0")
                        .license("v1.0.0-Apache2.0")
                        .build());
    }
}

具體使用

物體類

描述、必填、隱藏
在這里插入圖片描述

2.x版本
/**
 * @Author bennyrhys
 */
@ApiModel(description = "用戶資訊描述類")
public class User {
    @ApiModelProperty(value = "用戶id")
    private Integer id;
    @ApiModelProperty(value = "用戶名")
    private String username;
    @ApiModelProperty(value = "用戶地址")
    private String address;

1.x版本
@ApiModelProperty(value = "Topic串列", required = false, hidden = true)

controller

建議不加value
加operation的描述方法
加是否必傳

    // 可以不展示此介面
//    @ApiIgnore

查詢，是否必要

    /**
     * 查詢用戶 【頁面引數query】
     * @param id
     * @return
     */
    // 方法 方法描述
    @ApiOperation(value = "查詢用戶",notes = "根據用戶id查詢用戶 ")
    // 引數 引數描述 引數必填【針對swagger】
//    @ApiImplicitParam(name = "id", value = "用戶id", required = true, defaultValue = "99")
    @GetMapping("/user")
    public User getUserById(Integer id) {
        User user = new User();
        user.setId(id);
        return user;
    }

洗掉，回傳值

    @ApiOperation(value = "洗掉用戶",notes = "根據用戶id洗掉用戶")
    @ApiImplicitParam(name = "id", value = "用戶id", required = true, defaultValue = "99")
    @ApiResponses({
            @ApiResponse(code = 200, message = "洗掉成功"),
            @ApiResponse(code = 500, message = "洗掉失敗")
    })

更新，多引數

    /**
     * 更新用戶
     */
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用戶id", required = true, defaultValue = "99"),
            @ApiImplicitParam(name = "username", value = "用戶名", required = true, defaultValue = "bennyrhys")
    })
    @ApiOperation(value = "更新用戶",notes = "根據用戶id更新用戶名")