Java テクノロジー - インターフェイス ドキュメント - Swagger2&Swagger3&インターフェイス ドキュメント UI 統合

目次

1.Swagger2の完全な使い方

1. POM の依存関係

2. インターフェースクラス

3. 実装クラス

4. 静的リソースのホスト

5. インターフェースドキュメントの構成

6. 運用環境がインターフェースドキュメントを閉じます。

7. Swagger3 ページ効果

2. Swagger3の完全な使い方

3. Swagger は Knife4jUi を統合します

1. POM の依存関係

2. インターフェースクラス

3. 実装クラス

4. 静的リソースのホスト

5. インターフェースドキュメントの構成

6. 運用環境がインターフェースドキュメントを閉じます。

4. 注意事項とパラメータの説明

1.@Api()

2.@ApiOperation()

3. @ApiParam()

4.@ApiModel()

5.@ApiModelProperty()

6. @ApiImplicitParams() と @ApiImplicitParam()

---

スワッガーの説明

Swaggerは、企業内のインターフェース（API）の統一標準仕様を定義するためのドキュメント生成ツールです。バックエンドの大手仲間の怠惰には便利ですが、アノテーションを書くのも面倒ですが、バージョンのイテレーションが速かったり、人材の流動性が大きかったりすると、多くの問題が発生します。したがって、多くの企業はインターフェイス標準を定義するための統一仕様書を作成することになります。

1.Swagger2の完全な使い方

1. POM の依存関係

<プロパティ>
   <springfox-swagger.version>2.9.2</springfox-swagger.version>
</properties>

<dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>${springfox-swagger.version}</version>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>${springfox-swagger.version}</version>
            </dependency>

2. インターフェースクラス

[3.2]を参照してください。

3. 実装クラス

[3.3]を参照してください。

4. 静的リソースのホスト

import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

@EnableSwagger2
@EnableWebMvc
@Configuration
public class ApiDocConfiguration extends WebMvcConfigurerAdapter {


    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {

        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");

        super.addResourceHandlers(registry);

    }

}

5. インターフェースドキュメントの構成

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

@Configuration
public class SwaggerConf {
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()).enable(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ikong.service.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("开放接口平台")
                .description("")
                .contact(new Contact("ikong", "http://ikong.ik.com", "[email protected]"))
                .version("1.0")
                .build();
    }
}

6. 運用環境がインターフェースドキュメントを閉じます。

[3.6]を参照してください。

7. Swagger3 ページ効果

Swagger2マルチパッケージ実装方法

2. Swagger3の完全な使い方

1. POM の依存関係

2. インターフェースクラス

3. 実装クラス

4. 静的リソースのホスト

5. インターフェースドキュメントの構成

6. 運用環境がインターフェースドキュメントを閉じます。

7. Swagger3 ページ効果

3. Swagger は Knife4jUi を統合します

1. POM の依存関係

<プロパティ>
    <knife4j-swagger.version>3.0.3</knife4j-swagger.version>
</properties>

<依存関係> 
    <groupId>com.github.xiaoymin</groupId> 
    <artifactId>knife4j-spring-boot-starter</artifactId> 
    <version>${knife4j-swagger.version}</version> 
</dependency>

2. インターフェースクラス

import com.ikong.model.req.TestReq;
import com.ikong.model.ret.TestRet;
import com.jd.security.framework.common.model.Result;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestParam;

public interface TestApi {

    String test1(@RequestParam(value = "name") String name);

    TestRet test2(@RequestBody TestReq req);

    Result<TestRet> test3(@RequestBody TestReq req);
}

3. 実装クラス

import com.ikong.api.TestApi;
import com.ikong.model.req.TestReq;
import com.ikong.model.ret.TestRet;
import com.jd.security.framework.common.model.Result;
import com.jd.security.framework.common.model.ResultUtils;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

@Api(tags = "验证参数类型")
@RestController
@RequestMapping("/test")
public class TestApiController implements TestApi {

    @ApiOperation("001接收普通参数")
    @ApiImplicitParam(name = "name", value = "姓名", required = true)
    @GetMapping("test1")
    @Override
    public String test1(@RequestParam(value = "name") String name) {
        return "hello," + name;
    }

    @ApiOperation("002接收对象参数")
    @GetMapping("test2")
    @Override
    public TestRet test2(TestReq req) {
        return new TestRet(Long.valueOf(req.getId()), 200);
    }

    @ApiOperation("003返回标准格式")
    @PostMapping("test3")
    @Override
    public Result<TestRet> test3(@RequestBody TestReq req) {
        return ResultUtils.wrapSuccess(new TestRet(Long.valueOf(req.getId()), 200));
    }
}

4. 静的リソースのホスト

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

@Configuration
public class ApiDocHandlerConfiguration extends WebMvcConfigurationSupport {

    @Value("${swagger.enable:true}")
    private Boolean enable = false;

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        if (enable) {
            registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
    }
}

5. インターフェースドキュメントの構成

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

import java.util.ArrayList;
import java.util.List;

@Configuration
@EnableSwagger2WebMvc
public class ApiDocKnife4jUiConfig {
    @Bean
    public Docket docket(Environment environment) {
        // 添加接口请求头参数配置 没有的话 可以忽略
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        tokenPar.name("token")
                .description("令牌")
                .defaultValue("")
                .modelRef(new ModelRef("string"))
                .parameterType("header").required(false).build();
        pars.add(tokenPar.build());
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(true)//是否启动swagger 默认启动
                .groupName("ikong")//所在分组
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ikong.service.impl"))//指定扫描的包路径
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars);
    }

    private ApiInfo apiInfo() {
        Contact author = new Contact("ikong", "api.ik.com", "[email protected]");
        return new ApiInfo(
                "开放平台接口文档",
                "开放平台接口文档",
                "1.0",
                "",
                author,
                "",
                "",
                new ArrayList<>()
        );

    }
}

6. 運用環境がインターフェースドキュメントを閉じます。

アプリケーションのプロパティ

swagger.enable=false

7. Knife4jUi ページ効果

URL :  http://localhost:8083/doc.html

4. 注意事項とパラメータの説明

パラメータの説明:
name -- パラメータ名
value -- パラメータの説明が
必要 -- 入力するかどうか
dataType -- データ型
paramType -- パラメータの型
example --
一般的に使用される注釈の例:

• クラスの場合は @Api()。

このクラスを Swagger として識別するリソースを表します

• メソッドの場合は @ApiOperation()。

httpリクエストの操作を表します

• @ApiParam() はメソッド、パラメータ、フィールドの説明に使用されます。

パラメータへのメタデータの追加を示します（説明や必須かどうかなど）。

• クラスの @ApiModel()

エンティティクラスでパラメータを受け取るために使用されるクラスの説明を示します。

• メソッド、フィールドの場合は @ApiModelProperty()

モデル属性の説明またはデータ操作の変更を示します。

• @ApiIgnore() クラス、メソッド、メソッドパラメータの場合

このメソッドまたはクラスが無視されることを示します

• メソッドの @ApiImplicitParam()

個々のリクエストパラメータを示します

• 複数の @ApiImplicitParams を含むメソッドの @ApiImplicitParams()

具体的な使用説明:

1.@Api()

  ···
  @Api("测试用例1")
  @Controller
  public class swaggerTestUse(){
  }

2.@ApiOperation()

···
@Api("测试用例1")
@Controller
public class swaggerTestUse(){
    @ApiOperation(value = "apiOperationSwaggerTest", notes = "apiOperationSwagger测试")
    public void apiOperationSwaggerTest(){
    }
}

3. @ApiParam()

···
@Api("测试用例1")
@Controller
public class swaggerTestUse(){
    @ApiOperation(value = "apiOperationSwaggerTest", notes = "apiOperationSwagger测试")
    public void apiOperationSwaggerTest(@ApiParam(name = "id", value = "id入参", required = true) Integer id){
    }
}

4.@ApiModel()

···
@ApiModel(description = "测试实体类", value = "测试实体类")
public class Album implements Serializable {
    ···
}

5.@ApiModelProperty()

···
@ApiModel(description = "测试实体类", value = "测试实体类")
public class User implements Serializable {
    @ApiModelProperty(name = "userName", value = "用户名", required = false, exmaple = "小明")
    private String userName;
}

6. @ApiImplicitParams() と @ApiImplicitParam()

    ···
  @Api("测试用例1")
  @Controller
  public class swaggerTestUse(){
      @ApiOperation(value = "apiOperationSwaggerTest", notes = "apiOperationSwagger测试")
      @ApiImplicitParams({@ApiImplicitParam(name = "id", value = "id入参", required = true, dataType = "Integer", paramType = "query"),
                        @ApiImplicitParam(name = "brand", value = "brand", required = true, dataType = "BRAND", paramType = "body")
    })
      public void apiOperationSwaggerTest(Integer id, Brand band){
      }
  }