SpringBoot integriert Swagger2, um Schnittstellendokumente zu generieren. Mama muss sich keine Sorgen mehr machen, dass ich API-Dokumente schreibe.

Im aktuellen Entwicklungsprozess werden API-Schnittstellen grundsätzlich für die Systementwicklung verwendet. Daher ist in diesem Prozess ein gutes API-Dokument zum Backend und Frontend für Kommunikation und Entwicklung geworden.

Der traditionelle Ansatz besteht darin, dass Entwickler ein RESTful-API-Dokument erstellen, um alle Schnittstellendetails aufzuzeichnen. Ehrlich gesagt ist der Arbeitsaufwand nicht gering und sehr trivial, und wenn das Projekt aktualisiert wird, treten die folgenden Probleme auf geschehen.

• Die Dokumentation ist schwierig zu pflegen.

• Der Inhalt der Benutzeroberfläche ist komplexer und die Schreibeffizienz geringer.

Swagger soll dieses Problem lösen. Als standardisiertes und vollständiges Framework kann es zum Generieren, Beschreiben, Aufrufen und Visualisieren von Webdiensten im RESTful-Stil verwendet werden:

Durch Mit Swagger können wir API-Schnittstellendokumente mithilfe von Anmerkungen während des Schnittstellenentwicklungsprozesses automatisch generieren/aktualisieren und das Schnittstellen-Debugging auf der Dokumentationsseite unterstützen.

Als nächstes sprechen wir kurz darüber, wie man Swagger2 in SpringBoot integriert (2 stellt seine Version dar)

Einführung der Swagger2-Abhängigkeit

pom.xml Datei

<dependencies>
        <!--Swagger2 在此，个人推荐使用2.8.0版本，较为稳定-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>
</dependencies>

Konfigurationsdatei erstellen

Swagger2Config.javaJava-Konfigurationsdatei

@Configuration
// 指定扫描的api包路径
@ComponentScan(basePackages = {"cn.beatree.xxx.controller"})
//注解开启 swagger2 功能
@EnableSwagger2
public class Swagger2Config {
    @Value("${swagger2.enable}")
    boolean enable;
    // 配置文件中通过值注入控制生产环境与开发环境下的启用状态
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(enable)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("ANONVOTE | Swagger API文档")//标题
                .description("description: ANONVOTE | Swagger API文档")//描述
                .contact("BEATREE")//作者信息
                .version("1.0.0")//版本号
                .build();
    }
}

application.ymlKonfigurationsdatei

swagger2:
  enable: false #true 启用

@Configuration Annotation, die als Konfigurationsklasse bezeichnet wird, wird beim Start von SpringBoot geladen.

@EnableSwagger2 Annotation zum Aktivieren von Swagger2.

Mitgliedsmethode createRestApi Funktion erstellt das Docket Bean, apiInfo() Grundlegende Informationen, die zum Erstellen der API verwendet werden (diese grundlegenden Informationen werden auf der Dokumentationsseite angezeigt). Die Funktion select() gibt einen ApiSelectorBuilder zurück Die Instanz wird verwendet, um zu steuern, welche Schnittstellen Swagger zur Anzeige bereitgestellt werden. In diesem Beispiel wird sie durch Angabe des gescannten Paketpfads definiert, der alle Controller unter dem Paket scannt. Definiert die API und erzeugt Dokumentationsinhalte (außer für Anfragen, die durch @ApiIgnore angegeben werden).

Häufig verwendete Swagger-Anmerkungen

@Api: Ändern Sie die gesamte Klasse und beschreiben Sie die Rolle des Controllers

@ApiOperation: beschreibt eine Methode einer Klasse oder einer Schnittstelle

@ApiParam: beschreibt einen einzelnen Parameter @ApiModel : Verwendet ein Objekt zum Empfangen von Parametern

@ApiProperty: Wenn Sie ein Objekt zum Empfangen von Parametern verwenden, beschreiben Sie ein Feld des Objekts

@ApiResponse: Eine Beschreibung der HTTP-Antwort

@ApiResponses: Die Gesamtbeschreibung der HTTP-Antwort

@ApiIgnore : Verwenden Sie diese Annotation, um diese API zu ignorieren

@ApiError : Informationen, die zurückgegeben werden, wenn ein Fehler tritt auf

@ApiImplicitParam: Beschreibt einen Anforderungsparameter, Sie können die chinesische Bedeutung des Parameters konfigurieren und Sie können auch den Standardwert für den Parameter festlegen

@ApiImplicitParams: Beschreibt eine Anforderungsparameterliste, die aus mehreren mit

@ApiImplicitParam annotierten Parametern besteht

Zum Beispiel

@RestController
@Transactional    // 事务注解，实现回滚
@RequestMapping("/api/tlink")
@Api(value = "/api/tlink", tags = "参与者相关接口")
public class TlinkController{
    @GetMapping("/checkCode/{code}")
    @ApiOperation(value = "投票认证码核验接口",
            notes = "该接口用于核验认证码合法性，对于投票主题内容的获取需后续调用Topic相关接口。返回值data中带有参数 topic & options")
    public JSONObject checkCode(@PathVariable("code") String code){
  ...
 }
}

Zuletzt, nachdem Sie das SpringBoot-Projekt ausgeführt haben, greifen Sie über die Serveradresse /swagger-ui.html darauf zu.

Es ist zu beachten, dass, wenn ein Pfad-Interceptor hinzugefügt wurde, der Swagger-Pfad über

.excludePathPatterns("/swagger-resources/**", "/webjars/**", "/v2/**", "/swagger-ui.html/**")

freigegeben werden muss.

Das obige ist der detaillierte Inhalt vonSpringBoot integriert Swagger2, um Schnittstellendokumente zu generieren. Mama muss sich keine Sorgen mehr machen, dass ich API-Dokumente schreibe.. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!