Swagger UI und Dokumentationsveröffentlichung Tutorial
Swagger UI ist ein Visualisierungswerkzeug für API-Dokumentation basierend auf der OpenAPI-Spezifikation (früher Swagger-Spezifikation). Es kann API-Spezifikationsdokumente in eine interaktive API-Dokumentationsoberfläche umwandeln.
Durch Swagger UI können Entwickler und Benutzer:
- Detaillierte Informationen über die API anzeigen
- API-Anfragen direkt in der Oberfläche testen
- Anfrage- und Antwortbeispiele anzeigen
- Die Funktionalität und Parameter verschiedener API-Endpunkte verstehen
Vorteile von Swagger UI
- Visualisierung: Bietet eine klare und intuitive API-Dokumentationsoberfläche
- Interaktivität: Unterstützt Online-API-Tests ohne zusätzliche Tools
- Echtzeit-Aktualisierungen: Die Dokumentation wird nach Codeänderungen automatisch aktualisiert
- Standardisierung: Basierend auf der OpenAPI-Spezifikation, Konsistenz beibehalten
- Sprachübergreifende Unterstützung: Anwendbar auf verschiedene Programmiersprachen und Frameworks
Swagger UI integrieren
1. Integration in ein Spring Boot-Projekt
Abhängigkeiten hinzufügen
Inpom.xmlFügen Sie die folgenden Abhängigkeiten hinzu:
Beispiel
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>3.0.0</version>
</dependency>
<!-- Springfox Swagger UI -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>3.0.0</version>
</dependency>
Oder verwenden Sie SpringDoc OpenAPI:
Beispiel
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.14</version>
</dependency>
Swagger konfigurieren
Beispiel
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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.controller"))
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("API-Dokumentation")
.description("Detaillierte Beschreibung der API")
.version("1.0.0")
.contact(new Contact("Entwicklungsteam", "https://example.com", "team@example.com"))
.build();
}
}
Für SpringDoc OpenAPI:
Beispiel
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.Contact;
@Configuration
public class SwaggerConfig {
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(new Info()
.title("API-Dokumentation")
.version("1.0.0")
.description("Detaillierte Beschreibung der API")
.contact(new Contact()
.name("Entwicklungsteam")
.email("team@example.com")
.url("https://example.com")));
}
@Bean
public GroupedOpenApi publicApi() {
return GroupedOpenApi.builder()
.group("public-apis")
.pathsToMatch("/api/**")
.build();
}
}
2. Integration in ein Node.js-Express-Projekt
Abhängigkeiten installieren
npm install swagger-jsdoc swagger-ui-express --save
Swagger konfigurieren
Beispiel
const swaggerJsDoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');
const app = express();
// Swagger-Konfiguration
const swaggerOptions = {
Definition: {
openapi: '3.0.0',
Info: {
title: 'API-Dokumentation',
version: '1.0.0',
description: 'Detaillierte Beschreibung der API',
contact: {
name: 'Entwicklungsteam',
email: 'team@example.com',
url: 'https://example.com'
}
},
servers: [
{
url: 'http://localhost:3000',
description: 'Entwicklungsserver'
}
]
},
apis: ['./routes/*.js'] // Pfad zur API-Routendatei
};
const swaggerDocs = swaggerJsDoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));
// ... weitere Routen und Middleware
app.listen(3000, () => {
console.log('Server läuft unter http://localhost:3000');
console.log('API-Dokumentation ist unter http://localhost:3000/api-docs verfügbar');
});
3. Verwendung in einem Python-FastAPI-Projekt
FastAPI integriert Swagger UI standardmäßig:
Beispiel
app = FastAPI(
title="API-Dokumentation",
description="Detaillierte Beschreibung der API",
version="1.0.0",
contact={
"name": "Entwicklungsteam",
"email": "team@example.com",
"url": "https://example.com",
},
)
@app.get("/")
async def root():
return {"message": "Hello World"}
Swagger UI ist standardmäßig unter dem Pfad /docs erreichbar. Sie können die Dokumentation unter http://localhost:8000/docs anzeigen.
Für Details siehe:Interaktive API-Dokumentation von FastAPI
API-Dokumentation schreiben
1. API-Dokumentationsannotationen in einem Spring Boot-Projekt
Beispiel
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/api/users")
@Api(tags = "Benutzerverwaltung")
public class UserController {
@ApiOperation(value = "Benutzerliste abrufen", notes = "Alle Benutzerinformationen mit Paginierung abrufen")
@ApiResponses({
@ApiResponse(code = 200, message = "Erfolg"),
@ApiResponse(code = 400, message = "Ungültige Anfrageparameter"),
@ApiResponse(code = 500, message = "Interner Serverfehler")
})
@GetMapping("/")
public Page<User> getUsers(
@ApiParam(value = "Seitennummer", required = true) @RequestParam int page,
@ApiParam(value = "Anzahl der Datensätze pro Seite", required = true) @RequestParam int size) {
// Geschäftslogik
return userService.getUsers(page, size);
}
@ApiOperation(value = "Einzelnen Benutzer abrufen", notes = "Benutzerinformationen anhand der ID abrufen")
@GetMapping("/{id}")
public User getUser(
@ApiParam(value = "Benutzer-ID", required = true) @PathVariable Long id) {
// Geschäftslogik
return userService.getUser(id);
}
@ApiOperation(value = "Benutzer erstellen", notes = "Einen neuen Benutzer erstellen")
@PostMapping("/")
public User createUser(
@ApiParam(value = "Benutzerinformationen", required = true) @RequestBody UserDTO userDTO) {
// Geschäftslogik
return userService.createUser(userDTO);
}
}
Für SpringDoc OpenAPI:
Beispiel
import io.swagger.v3.oas.annotations.media.*;
import io.swagger.v3.oas.annotations.responses.*;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/api/users")
@Tag(name = "Benutzerverwaltung", description = "Benutzerbezogene APIs")
public class UserController {
@Aktion(
summary = "Benutzerliste abrufen",
description = "Alle Benutzerinformationen mit Paginierung abrufen"
)
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "Erfolg"),
@ApiResponse(responseCode = "400", description = "Ungültige Anfrageparameter"),
@ApiResponse(responseCode = "500", description = "Interner Serverfehler")
})
@GetMapping("/")
public Page<User> getUsers(
@Parameter(description = "Seitennummer", required = true) @RequestParam int page,
@Parameter(description = "Anzahl der Datensätze pro Seite", required = true) @RequestParam int size) {
// Geschäftslogik
return userService.getUsers(page, size);
}
}
2. API-Dokumentationskommentare in einem Node.js-Express-Projekt
Beispiel
* @swagger
* /api/users:
* get:
* summary: Benutzerliste abrufen
* description: Alle Benutzerinformationen mit Paginierung abrufen
* tags: [Benutzerverwaltung]
* parameters:
* - in: query
* name: page
* schema:
* type: integer
* required: true
* description: Seitennummer
* - in: query
* name: size
* schema:
* type: integer
* required: true
* description: Anzahl der Datensätze pro Seite
* responses:
* 200:
* description: Erfolg
* content:
* application/json:
* schema:
* type: object
* properties:
* data:
* type: array
* items:
* $ref: '#/components/schemas/User'
* total:
* type: integer
* 400:
* description: Ungültige Anfrageparameter
* 500:
* description: Interner Serverfehler
*/
router.get('/users', (req, res) => {
// Geschäftslogik
});
/**
* @swagger
* components:
* schemas:
* User:
* type: object
* required:
* - name
* properties:
* id:
* type: integer
* description: Benutzer-ID
* name:
* type: string
* description: Benutzername
* email:
* type: string
* format: email
* description: Benutzer-E-Mail
*/
3. API-Dokumentation in einem Python-FastAPI-Projekt
Beispiel
from pydantic import BaseModel
from typing import List, Optional
app = FastAPI(title="Benutzerverwaltungs-API")
class User(BaseModel):
id: int
name: str
email: str
class Config:
schema_extra = {
"example": {
"id": 1,
"name": "Zhang San",
"email": "zhangsan@example.com"
}
}
@app.get(
"/api/users/",
summary="Benutzerliste abrufen",
description="Alle Benutzerinformationen mit Paginierung abrufen",
response_model=List[User],
tags=["Benutzerverwaltung"]
)
async def get_users(
page: int = Query(..., description="Seitennummer", ge=1),
size: int = Query(..., description="Anzahl der Datensätze pro Seite", ge=1, le=100)
):
# Geschäftslogik
return [
{"id": 1, "name": "Zhang San", "email": "zhangsan@example.com"},
{"id": 2, "name": "Li Si", "email": "lisi@example.com"}
]
@app.get(
"/api/users/{user_id}",
summary="Einzelnen Benutzer abrufen",
description="Benutzerinformationen nach ID abrufen",
response_model=User,
tags=["Benutzerverwaltung"]
)
async def get_user(
user_id: int = Path(..., Beschreibung="Benutzer-ID", ge=1)
):
# Geschäftslogik
return {"id": user_id, "name": "Zhang San", "email": "zhangsan@example.com"}
Anpassen der Swagger UI
1. Benutzerdefinierte Spring-Boot-Konfiguration
Beispiel
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.controller"))
.paths(PathSelectors.regex("/api/.*"))
.build()
.apiInfo(apiInfo())
.useDefaultResponseMessages(false) // Standardantwortnachrichten deaktivieren
.globalResponseMessage(RequestMethod.GET, globalResponses()) // Benutzerdefinierte globale Antwortnachrichten
.securitySchemes(Arrays.asList(apiKey())) // Sicherheitsauthentifizierung konfigurieren
.securityContexts(Arrays.asList(securityContext())); // Sicherheitskontext konfigurieren
}
private List<ResponseMessage> globalResponses() {
return Arrays.asList(
new ResponseMessageBuilder().code(200).message("Erfolg").build(),
new ResponseMessageBuilder().code(400).message("Ungültige Anfrageparameter").build(),
new ResponseMessageBuilder().code(401).message("Nicht autorisiert").build(),
new ResponseMessageBuilder().code(403).message("Verboten").build(),
new ResponseMessageBuilder().code(500).message("Interner Serverfehler").build()
);
}
private ApiKey apiKey() {
return new ApiKey("JWT", "Authorization", "header");
}
private SecurityContext securityContext() {
return SecurityContext.builder()
.securityReferences(defaultAuth())
.forPaths(PathSelectors.regex("/api/.*"))
.build();
}
private List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
return Arrays.asList(new SecurityReference("JWT", authorizationScopes));
}
2. Benutzerdefinierte Express-Konfiguration
Beispiel
customCss: '.swagger-ui .topbar { display: none }', // Benutzerdefiniertes CSS
customSiteTitle: "API-Dokumentationszentrum", // Seitentitel
customfavIcon: "/favicon.png", // Benutzerdefiniertes Icon
swaggerOptions: {
persistAuthorization: true, // Autorisierungsinformationen beibehalten
docExpansion: 'none', // Standardmäßig alle Schnittstellen einklappen
tagsSorter: 'alpha', // Tags alphabetisch sortieren
operationsSorter: 'alpha', // Operationen alphabetisch sortieren
defaultModelsExpandDepth: -1, // Modelle ausblenden
filter: true, // Filterung aktivieren
}
};
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs, options));
3. Benutzerdefinierte FastAPI-Konfiguration
Beispiel
from fastapi.openapi.docs import get_swagger_ui_html
from fastapi.staticfiles import StaticFiles
app = FastAPI(
title="API-Schnittstellendokumentation",
docs_url=None, # Standard-Swagger-UI deaktivieren
)
app.mount("/static", StaticFiles(directory="static"), name="static")
@app.get("/docs", include_in_schema=False)
async def custom_swagger_ui_html():
return get_swagger_ui_html(
openapi_url=app.openapi_url,
title=app.title + " - API-Dokumentation",
oauth2_redirect_url=app.swagger_ui_oauth2_redirect_url,
swagger_js_url="/static/swagger-ui-bundle.js",
swagger_css_url="/static/swagger-ui.css",
swagger_favicon_url="/static/favicon.png",
swagger_ui_parameters={
"docExpansion": "none",
"defaultModelsExpandDepth": -1,
"filter": True,
}
)
Veröffentlichung der Dokumentation
1. Interne Veröffentlichung
Zur internen Verwendung durch das Team können Sie direkt auf die Swagger UI innerhalb der Anwendung zugreifen:
- Spring Boot:
http://your-app-host:port/swagger-ui/index.html - Express:
http://your-app-host:port/api-docs - FastAPI:
http://your-app-host:port/docs
2. Statische Dokumentationsgenerierung
Verwenden Sie Swagger Codegen, um statische Dokumentation zu generieren
# 安装 Swagger Codegen CLI wget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.35/swagger-codegen-cli-3.0.35.jar -O swagger-codegen-cli.jar # 生成静态 HTML 文档 java -jar swagger-codegen-cli.jar generate -i http://your-app-host:port/v3/api-docs -l html2 -o ./api-docs
Verwenden Sie Redoc, um statische Dokumentation zu generieren
# 安装 redoc-cli npm install -g redoc-cli # 生成静态 HTML 文档 redoc-cli bundle http://your-app-host:port/v3/api-docs -o ./api-docs/index.html
3. Integration in die CI/CD-Pipeline
Fügen Sie der CI/CD-Pipeline Schritte zum Generieren und Veröffentlichen von Dokumentation hinzu:
Jenkins-Pipeline-Beispiel
Beispiel
agent any
stages {
// ... weitere Build- und Test-Stufen
stage('API-Dokumentation generieren') {
steps {
sh 'java -jar swagger-codegen-cli.jar generate -i http://your-app-host:port/v3/api-docs -l html2 -o ./api-docs'
}
}
stage('Dokumentation veröffentlichen') {
steps {
// Auf statischem Nginx-Dateiserver veröffentlichen
sh 'rsync -avz --delete ./api-docs/ user@doc-server:/var/www/api-docs/'
// Oder in Objektspeicher veröffentlichen (z. B. AWS S3)
sh 'aws s3 sync ./api-docs/ s3://your-bucket/api-docs/ --delete'
}
}
}
}
GitHub Actions Workflow-Beispiel
Beispiel
auf:
push:
branches: [ main ]
jobs:
build-und-deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: JDK einrichten
uses: actions/setup-java@v2
with:
distribution: 'adopt'
java-version: '11'
- name: Anwendung bauen
run: ./mvnw clean package
- name: Anwendung starten
run: |
java -jar target/your-app.jar &
sleep 30# Warten auf den Start der Anwendung
- name: API-Dokumentation generieren
run: |
wget -q https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.35/swagger-codegen-cli-3.0.35.jar -O swagger-codegen-cli.jar
java -jar swagger-codegen-cli.jar generate -i http://localhost:8080/v3/api-docs -l html2 -o ./api-docs
- name: Auf GitHub Pages bereitstellen
uses: JamesIves/github-pages-deploy-action@4.1.5
with:
branch: gh-pages
folder: api-docs
4. Verwenden einer Plattform für API-Dokumentationsmanagement
Neben der Selbstbereitstellung können Sie auch professionelle Plattformen zur Verwaltung von API-Dokumentation verwenden:
- Swagger Hub: Bietet Hosting-Dienste für API-Design und Dokumentation
- Postman: Ermöglicht das Testen von APIs und auch das Veröffentlichen von API-Dokumentation
- ReadMe.io: Bietet umfassendes Management für API-Dokumentation und ein Entwicklerportal
- Stoplight: Bietet Tools für API-Design, Dokumentation und Governance
5. Bereitstellung von Swagger UI mit Docker
Beispiel
# Umgebungsvariablen setzen
ENV SWAGGER_JSON=/swagger/openapi.json
ENV BASE_URL=/api-docs
# OpenAPI-Spezifikationsdatei kopieren
COPY openapi.json /swagger/
# Port freigeben
EXPOSE 8080
# Swagger UI starten
CMD ["sh", "/usr/share/nginx/docker-run.sh"]
Erstellen und ausführen:
docker build -t my-swagger-ui . docker run -p 8080:8080 my-swagger-ui
Zugriff: http://localhost:8080/api-docs
Best Practices
1. Dokumentationsstandards
- Prägnant und klar halten: Beschreibungen sollten prägnant und zielgerichtet sein
- Gruppenverwaltung: Verwenden Sie Tags, um APIs logisch zu gruppieren
- Beispiele bereitstellen: Beispiele für Anfragen und Antworten bereitstellen
- Fehlerbehandlung standardisieren: Fehlerantwortformat und Statuscodes standardisieren
- Versionsverwaltung: API-Versionsinformationen in der Dokumentation klar angeben
2. Sicherheitskonfiguration
- Umgang mit sensiblen Informationen: Keine sensiblen Informationen in der Dokumentation offenlegen
- Konfiguration der Produktionsumgebung: Dokumentationszugriff in der Produktion optional deaktivieren oder einschränken
- Authentifizierungsmechanismus: Authentifizierung für den Zugriff auf die Dokumentation konfigurieren
Beispiel
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.enable(!environment.acceptsProfiles(Profiles.of("prod")))
// ... weitere Konfigurationen
}
3. Automatisiertes Testen
Kombinieren Sie Dokumentation und Tests, um sicherzustellen, dass der Dokumentationsinhalt mit dem tatsächlichen API-Verhalten konsistent bleibt:
Beispiel
@Test
public void validateSwaggerDocumentation() {
// Swagger-JSON abrufen
String swaggerJson = given()
.when()
.get("/v3/api-docs")
.dann()
.statusCode(200)
.extract().asString();
// Swagger-Dokumentation überprüfen
OpenAPI openAPI = new OpenAPIParser().readContents(swaggerJson, null, null).getOpenAPI();
assertNotNull(openAPI);
// Überprüfen, ob ein bestimmter Endpunkt in der Dokumentation existiert
assertNotNull(openAPI.getPaths().get("/api/users"));
}
Fehlerbehebung bei häufigen Problemen
1. Swagger UI wird nicht angezeigt oder es treten Ladefehler auf
- Abhängigkeitsversionen prüfen: Stellen Sie sicher, dass Abhängigkeitsversionen kompatibel sind
- Konfigurationsklassen prüfen: Stellen Sie sicher, dass Konfigurationsklassen korrekt registriert sind
- Pfadzuordnungen prüfen: Stellen Sie sicher, dass Pfadzuordnungen korrekt sind
- Cross-Origin-Einstellungen prüfen: Wenn Sie ursprungsübergreifend zugreifen, stellen Sie sicher, dass die CORS-Konfiguration korrekt ist
2. Unvollständige API-Informationen
- Annotationen prüfen: Stellen Sie sicher, dass alle notwendigen Annotationen hinzugefügt wurden
- Paket-Scanpfade prüfen: Stellen Sie sicher, dass die Scanpfade alle Controller einschließen
- Modellklassen prüfen: Stellen Sie sicher, dass Modellklassen korrekte Beschreibungen haben
3. Sicherheitsprobleme in der Produktionsumgebung
Konfigurieren Sie die Produktion, um die Dokumentation zu deaktivieren oder zu schützen:
# application-prod.properties springdoc.swagger-ui.enabled=false springdoc.api-docs.enabled=false
Oder mit Basisauthentifizierung schützen:
Beispiel
@Profile("prod")
public class SwaggerSecurityConfig extends WebSecurityConfigurerAdapter {
@Override
protected void configure(HttpSecurity http) throws Exception {
http.requestMatchers()
.antMatchers("/swagger-ui/**", "/v3/api-docs/**")
.und()
.authorizeRequests()
.anyRequest().hasRole("ADMIN")
.und()
.httpBasic();
}
}
Zusammenfassung
Swagger UI ist ein leistungsstarkes API-Dokumentationswerkzeug. Bei richtiger Konfiguration und Nutzung kann es die API-Nutzbarkeit und Entwicklungseffizienz erheblich verbessern. Dieses Tutorial führt in die grundlegenden Konzepte von Swagger UI, Integrationsmethoden, das Schreiben von Dokumentation, benutzerdefinierte Konfiguration, die Veröffentlichung von Dokumentation und Best Practices ein und hofft, für Ihre API-Dokumentationsarbeit hilfreich zu sein.
Beachten Sie die folgenden wichtigen Punkte:
- Wählen Sie eine Swagger-Integrationsmethode, die zum Technologie-Stack Ihres Projekts passt
- Entwerfen und schreiben Sie API-Dokumentationsannotationen oder -kommentare sorgfältig
- Passen Sie die Swagger-UI-Oberfläche nach Bedarf an
- Wählen Sie eine geeignete Methode zur Veröffentlichung der Dokumentation
- Befolgen Sie Best Practices, um Genauigkeit und Sicherheit der Dokumentation zu gewährleisten
Durch die richtige Nutzung von Swagger UI können Sie professionelle, interaktive Dokumentation für Ihre API bereitstellen, wodurch Ihre API leichter zu verstehen und zu verwenden ist.
Andere Erweiterungen