springBoot(12)---整合Swagger2

Spingboot整合Swagger2

        隨着互聯網技術的發展，一般開發都是前后端分離，那么前端和后端的唯一聯系，變成了API接口；API文檔變成了前后端開發人員聯系的紐帶，變得越來越重要，沒有API

文檔工具之前，大家都是手寫API文檔的，在什么地方書寫的都有，有在confluence上寫的，有在對應的項目目錄下readme.md上寫的，每個公司都有每個公司的玩法，無所謂好

壞。但都有一個很大的詬病就是，如果你的接口改動了，那你必須記得去改你的API文檔，而Swagger並不需要。swagger就是一款讓你更好的書寫API文檔的框架。

一、項目搭建

   1、pom.xml

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

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

   2、application.yml

server:
  port: 8086

#代表當前環境是dev環境
spring:
  profiles:
    active: dev

   3、Swagger2DevConfig（配置類）

注意添加@EnableSwagger2注解，這個注解也可以加在springboot啟動類上

@Configuration
@EnableSwagger2 public class Swagger2DevConfig {

    //默認pro環境
    @Profile({"default", "pro"})
    @Bean
    public Docket createWebApi() {
        return new Docket(DocumentationType.SWAGGER_2).enable(false).select().build();
    }

    //dev環境接口訪問地址:http://localhost:8086/swagger-ui.html
    @Profile("dev")
    @Bean
    public Docket createWebApiDev() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfoDev()).select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)).paths(PathSelectors.any()).build();
    }

    //測試環境接口訪問地址: test.jincou.com/user/swagger-ui.html
    @Profile("test")
    @Bean
    public Docket createWebApiTest() {
        return new Docket(DocumentationType.SWAGGER_2).host("test.jincou.com/user")
                .protocols(Sets.newHashSet("https")).apiInfo(apiInfoDev()).select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)).paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfoDev() {
        return new ApiInfoBuilder().title("用戶模塊API").description(
                "用戶api接口文檔\n" + "\n" + "測試環境:https://test.jincou.com/user\n").contact(new Contact("張三", "", ""))
                .version("1.0").build();
    }
}

      4、PersonController

    這里提供了兩個接口

@Api(tags = "用戶相關接口")
@RestController
@RequestMapping(value = "/web/api/person")
public class PersonController {


    @ApiOperation(value = "用戶詳細信息", notes = "通過id獲得用戶詳細信息")
    @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用戶ID", required = true, paramType = "query", defaultValue = "0")})
    @RequestMapping(value="page",method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_UTF8_VALUE )
    public Person  getById(@RequestParam(value="id",defaultValue = "0") Long id){
        return new Person(id,2,"小小","杭州");
    }

    //大咖分頁列表
    @ApiOperation(value = "刪除用戶信息", notes = "通過ID刪除用戶信息")
    @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用戶ID", required = true, paramType = "query", defaultValue = "0")})
    @RequestMapping(value="delete",method = RequestMethod.POST, produces = MediaType.APPLICATION_JSON_UTF8_VALUE )
    public String  delete(@RequestParam(value="id",defaultValue = "0") Long id){

        return "刪除成功";
    }
}

      5、Person實體類

@ApiModel(description = "用戶詳細信息")
public class Person {

    @ApiModelProperty(value = "用戶Id", position = 1)
    private Long id;

    @ApiModelProperty(value = "用戶年齡", position = 2)
    private int age;

  @ApiModelProperty(value = "用戶姓名", position = 3)
    private String name;

 @ApiModelProperty(value = "用戶所在城市", position = 4)
    private String city;

    public Person(Long id,int age,String name,String city){
        this.id=id;
        this.age=age;
        this.city=city;
        this.name=name;
    }
//提供get和set方法
}

     6、本地啟動測試

   訪問:http://localhost:8086/swagger-ui.html。

 

 

我只是偶爾安靜下來，對過去的種種思忖一番。那些曾經的舊時光里即便有過天真愚鈍，也不值得譴責。畢竟，往后的日子，還很長。不斷鼓勵自己，

天一亮，又是嶄新的起點，又是未知的征程（上校15）