swagger2的接口文檔

https://www.cnblogs.com/exmyth/p/7171857.html

 

以前見過一個swagger2的接口文檔，特別好用，好看，對接口中入參描述的很詳細；適合用於項目的開發

后來自己做項目的時候，沒有找到這個swagger版本

        <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>

　　這個版本的風格如下：

 

備注：

@Api: 描述類/接口的主要用途
@ApiOperation: 描述方法用途
@ApiImplicitParam: 描述方法的參數
@ApiImplicitParams: 描述方法的參數(Multi-Params)
@ApiParam:請求屬性
@ApiIgnore: 忽略某類/方法/參數的文檔
@ApiResponses：響應集配置
@ResponseHeader: 響應頭設置
@ApiModelProperty:添加和操作模型屬性的數據

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

　　換了個版本，三個2的版本，

高版本UI展示變了，高版本能顯示實體類中的對象屬性

不是之前我看到的，還是要繼續尋找更好的API接口文檔展示方式。。。。

 

 

項目測試的代碼

@Configuration
@EnableSwagger2  //通過@EnableSwagger2注解啟用Swagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2構建RESTful APIs")
                .description("更多Spring Boot相關文章請關注：https://home.cnblogs.com/u/qianjinyan/")
                .termsOfServiceUrl("https://github.com/JasmineQian/")
                .contact("夏天里的Jasmine")
                .version("1.0")
                .build();
        //配置一個Docket Bean，這個Bean中，配置映射路徑和要掃描的接口的位置，
        // 在apiInfo中，主要配置一下Swagger2文檔網站的信息，
        // 例如網站的title，網站的描述，聯系人的信息，使用的協議等等。
    }
}

　

package com.example.demo.entity;


import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel
public class User {

    @ApiModelProperty(value = "用戶id")
    private int id;

    @ApiModelProperty(value = "用戶名")
    private String name;

    @ApiModelProperty(value = "用戶地址")
    private String address;

省略getters and setters


    void addUser(int id,String name,String address){
        this.address=address;
        this.id=id;
        this.name=name;
    }
}

　　

package com.example.demo.controller;

import com.example.demo.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

@RestController
@Api(tags = "用戶管理相關接口")
@RequestMapping("/user")
public class UserController {

    @PostMapping("/addUser")
    @ApiOperation("添加用戶的接口")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用戶名", defaultValue = "李四"),
            @ApiImplicitParam(name = "address", value = "用戶地址", defaultValue = "深圳", required = true)}
    )
    public User addUser(String username, @RequestParam(required = true) String address) {
        return new User();
    }

    @GetMapping("/")
    @ApiOperation("根據id查詢用戶的接口")
    @ApiImplicitParam(name = "id", value = "用戶id", defaultValue = "1", required = true)
    public User getUserById(@PathVariable Integer id) {
        User user = new User();
        user.setId(id);
        return user;
    }

    @PutMapping("/{id}")
    @ApiOperation("根據id更新用戶的接口")
    public User updateUserById(@RequestBody User user) {
        return user;
    }
}